#Connections (MCP)
SignetMail can be connected to AI tools such as Claude through the Model Context Protocol (MCP), an open standard that lets an assistant call tools on your server. Once connected, you can ask in plain language:
- "Which signature does Ana Novak get, and why?"
- "List the rules in the order they are evaluated and tell me which ones have expired."
- "Show me the Liquid source of the
defaultsignature and suggest how to make it shorter." - "Which campaigns are running right now and how many clicks did they get?"
- "What changed in the portal this week?"
A human always has the last word. By default a connected tool can only read. A token can optionally also prepare changes (signature drafts, campaigns, disabled rules), but nothing it prepares ever goes live: a person must publish signatures, approve campaigns and enable rules in the portal. There is no tool that publishes, approves, enables, deletes or grants access. Everything is recorded in the audit log as
mcp:<token name>.
#What a connected tool can see
| Tool | What it returns |
|---|---|
list_organizations |
The organization tree and the fields available to templates as org.*. |
list_signatures |
Signatures with status (Draft, Live, Disabled), published version and pending changes. |
get_signature |
The Liquid/HTML source of a signature: the current draft and the published version. |
list_rules |
The assignment rules in evaluation order with criteria, time window and state (Active, Scheduled, Expired, Disabled). |
list_campaigns |
Campaigns with schedule, approval state and totals (inserted, clicks). |
search_users |
Directory users by name, e-mail, department or job title. |
preview_signature |
The signature a user would get now, or with a chosen published signature. Previews are not counted as insertions. |
get_audit_log |
The most recent portal changes, newest first. |
get_license_status |
License state, expiry and active users versus the limit. |
#Preparing changes (optional)
When you create a token, tick Can also prepare changes. That token also gets these tools:
| Tool | What it does | What still needs a person |
|---|---|---|
save_signature_draft |
Creates a signature (from the starter or a copy of another) or edits the draft of an existing one: Liquid/HTML and text, new message and reply. Omitted fields stay unchanged. | An Admin publishes it in the portal (Signatures). Until then users keep getting the published version. |
submit_signature_for_review |
Marks the draft as ready for review, like the Submit for review button. | The same publication step. |
save_campaign_draft |
Creates a banner campaign or changes one (by id). | An Admin approves it on the Campaigns page. Until then it is not inserted into signatures; any later change withdraws an earlier approval. |
propose_rule |
Creates a rule that is disabled. | An Admin enables it on the Rules page. Existing rules cannot be changed. |
preview_signature_draft |
Renders the current draft for a real person so the assistant can check its own work. Available to every token. |
The same checks as in the portal apply: templates must compile, HTML with scripts or event handlers is refused, campaign links must be https://, a rule can only use a signature of its own or a parent organization. When the license has expired, changes are locked (as in the portal) and these tools refuse to save.
A typical conversation: "Create a signature sale-2026 for organization primer based on default, add a one-line promotion, preview it for Ana Novak, and submit it for review." You then open the portal, look at the preview and press Publish.
Use a separate token for each person or tool, prefer read-only tokens when drafting is not needed, and review who has write tokens under Connections.
#Who can use a token
A token is created by an Owner and sees the whole system, so it is not limited to the organizations of the person who uses it. It exposes names, e-mail addresses, job titles and departments from your directory to the AI service you connect it to. Create tokens only for people and tools you trust, and read the privacy terms of the AI service you use.
#Create an access token
- Sign in to the portal as an Owner and open Connections.
- Enter a name (for example the tool and the person: Claude Code – Ana), choose when the token expires and whether it may also prepare changes.
- Select Create token. The token (it starts with
smt_) is shown once. Copy it now; only a hash is stored on the server, so it cannot be shown again. - The page shows ready-to-use commands for the clients below.
You can create as many tokens as you like (one per person or tool) and revoke any of them at any time under Connections; a revoked token stops working immediately. The list shows when each token was last used. Creating and revoking tokens is recorded in the audit log (the token itself never is), together with whether it is read-only.
#Connect a client
The MCP address is https://<host>/mcp, shown on the Connections page.
#Claude Code
claude mcp add --transport http signetmail https://<host>/mcp \
--header "Authorization: Bearer smt_…"
Or put it in a project file .mcp.json:
{
"mcpServers": {
"signetmail": {
"type": "http",
"url": "https://<host>/mcp",
"headers": { "Authorization": "Bearer smt_…" }
}
}
}
Then run /mcp in Claude Code to check that signetmail is connected.
#claude.ai and Claude Desktop
Open Settings → Connectors → Add custom connector, give it a name and paste the address with the token inside:
https://<host>/mcp/smt_…
These clients cannot send a custom Authorization header, so the token is part of the address. Treat the whole address like a password and do not share it. Plans and organization settings decide who may add custom connectors; on Team and Enterprise plans an organization owner may need to allow it.
#Other clients
Any client that supports remote MCP servers over Streamable HTTP works. Send the token in the header Authorization: Bearer smt_… (preferred) or use the address https://<host>/mcp/smt_…. Cursor accepts the same JSON as .mcp.json above.
#Security
- Hash only. The server stores a SHA-256 hash of each token. A leaked database does not leak usable tokens.
- Expiry and revocation. Choose an expiry when you create a token; revoke tokens that are no longer needed or may have leaked.
- Header preferred. A token in the address can end up in browser history or in logs of proxies you operate. The default SignetMail setup does not log request addresses; if you add access logging to your own reverse proxy, redact
/mcp/…paths. - Browser protection. Requests that carry an
Originheader (browsers) are refused unless the origin is your own server or listed inSignetMail:Mcp:AllowedOrigins. Desktop and server clients send noOriginand are not affected. - Rate limits and size limits of the API apply; a request may be at most 256 KB.
- Least privilege. Read-only is the default. Even a write token acts with the rights of an Editor (rules: only creating a disabled rule) and has no way to publish, approve, enable, delete or change access.
- Not indexed.
/mcpis excluded from search engines. - Independent of your license. Reading is not locked when a license expires (like viewing in the portal), and tokens can always be created and revoked.
#Switching it off
Set SignetMail:Mcp:Enabled to false (environment variable SignetMail__Mcp__Enabled=false) and restart. /mcp then returns 404 and the Connections page offers nothing to create. Existing tokens stay in the database and work again if you switch it back on.
#Technical details
- Transport: Streamable HTTP, stateless.
POST /mcpwith a JSON-RPC 2.0 message returns a JSON response; notifications return202.GETandDELETEreturn405(the server never pushes messages and keeps no sessions). - Protocol versions
2025-06-18,2025-03-26and2024-11-05are accepted; the server answers with the version the client asks for. - Methods:
initialize,ping,tools/list,tools/call. Read tools are annotatedreadOnlyHint: true; the tools of write tokens are annotatedreadOnlyHint: falseanddestructiveHint: false. Mistakes in a tool's input (an unknown user, a missing argument) come back as a tool result withisError: true, so the assistant can correct itself. - Test from a shell:
curl -s https://<host>/mcp \
-H "Authorization: Bearer smt_…" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
#Troubleshooting
| Symptom | Cause and fix |
|---|---|
401 Unauthorized |
The token is missing, mistyped, expired or revoked. Create a new one under Connections. |
404 Not Found on /mcp |
Connections are switched off (SignetMail:Mcp:Enabled) or the server runs an older version. |
403 Forbidden from a browser |
The request came from a web page on another origin. Add the origin to SignetMail:Mcp:AllowedOrigins only if you trust it. |
| The tool says "User … is not in the directory" | Directory sync has not run yet or the user is outside your sync scope. See Operations. |
| The tool says "No rule assigns a signature" | No active rule matches this person. Check the rules with list_rules or the Who gets which signature page. |
| Custom connector is missing in claude.ai | Your plan or organization does not allow it; ask an organization owner. |