MCP server
SecureThread for AI assistants
An MCP endpoint lets an AI assistant look things up in SecureThread and prepare email. The assistant acts as one signed-in employee, within that person’s permissions at the moment it acts.
One endpoint for every assistant
Assistants connect to https://app.securethread.co/mcp over Streamable HTTP. The server is stateless and keeps no session between requests.
OAuth 2.1 sign-in you approve
Assistants sign in with OAuth 2.1 and PKCE (S256). You approve each connection yourself, in your browser, and you can disconnect it at any time.
One person’s permissions
An assistant acts as one signed-in employee. The scopes it was granted and that person’s live permissions are both checked on every request.
Sends wait for a person
A person approves each email an assistant asks to send, unless your organization turns on automatic sending for narrow, low-risk emails. Scheduled sends and workflow runs an assistant starts always wait.
66 named, scoped tools
Every tool name starts with securethread_. Each tool has a strict input schema and an output schema, and the list each person sees follows their scopes and permissions.
Limits you can plan for
Requests are limited per connection and per person. Results are capped at 100,000 characters, and most lists return up to 25 items a page.
Explore
Every tool an assistant can call
Filter by scope or search by name. An assistant sees only the tools its granted scopes and its person's permissions allow.
66 of 66 tools
- securethread_get_connection_statusread
- securethread_get_current_userread
- securethread_get_provider_capabilitiesread
- securethread_list_connectionsread
- securethread_list_providersread
- securethread_preview_routingread
- securethread_get_templateread
- securethread_get_template_schemaread
- securethread_list_templatesread
- securethread_get_message_detailsread
- securethread_get_message_statusread
- securethread_list_delivery_attemptsread
- securethread_list_messagesread
- securethread_get_send_requestread
- securethread_get_usage_metricsread
- securethread_test_connectionmailboxes
- securethread_check_compatibilitytemplates
- securethread_create_templatetemplates
- securethread_create_template_versiontemplates
- securethread_publish_templatetemplates
- securethread_update_templatetemplates
- securethread_add_draft_attachmentcompose
- securethread_check_recipientscompose
- securethread_create_draftcompose
- securethread_get_draftcompose
- securethread_list_draftscompose
- securethread_preview_emailcompose
- securethread_render_emailcompose
- securethread_send_test_emailcompose
- securethread_update_draftcompose
- securethread_validate_emailcompose
- securethread_cancel_queued_messagesend
- securethread_retry_failed_messagesend
- securethread_send_emailsend
- securethread_list_contact_groupscontacts
- securethread_search_contactscontacts
- securethread_cancel_scheduleschedules
- securethread_create_scheduleschedules
- securethread_get_scheduleschedules
- securethread_list_schedulesschedules
- securethread_pause_scheduleschedules
- securethread_rescheduleschedules
- securethread_create_campaigncampaigns
- securethread_get_campaigncampaigns
- securethread_get_campaign_resultscampaigns
- securethread_list_campaignscampaigns
- securethread_pause_campaigncampaigns
- securethread_preview_campaigncampaigns
- securethread_cancel_workflow_runworkflows
- securethread_disable_workflowworkflows
- securethread_get_workflowworkflows
- securethread_get_workflow_run_statusworkflows
- securethread_list_workflow_runsworkflows
- securethread_list_workflowsworkflows
- securethread_run_workflowworkflows
- securethread_get_analytics_definitionsanalytics
- securethread_get_analytics_summaryanalytics
- securethread_list_delivery_incidentsanalytics
- securethread_get_approval_statusapprovals
- securethread_list_approval_requestsapprovals
- securethread_void_approval_requestapprovals or send
- securethread_get_provider_healthadmin
- securethread_get_system_healthadmin
- securethread_list_audit_eventsadmin
- securethread_list_rolesadmin
- securethread_list_usersadmin
01
Sign-in and consent
Turn AI assistant access on first. An administrator does this under Administration › AI access, and while it is off no assistant can connect or act. Then the assistant signs in with OAuth 2.1, and you approve the connection yourself in your browser.
- The endpoint answers a request without a token with 401 and a sign-in challenge. The challenge names the protected-resource document (RFC 9728), and the assistant then fetches the authorization server metadata (RFC 8414) from the same origin.
- Clients register themselves with dynamic client registration (RFC 7591), or present a Client ID Metadata Document at an https address.
- Each authorization request uses PKCE with the S256 method and a registered redirect URI. An https redirect must match exactly. A loopback http redirect (localhost, 127.0.0.1 or [::1]) matches on every part except the port.
- The consent page asks: Allow this app to use SecureThread as you? It shows the app’s name, the address the assistant will act as, the address the browser returns to, and the access levels.
- Verified domain means the app’s sign-in details are hosted on the domain shown. It confirms the domain, not who runs the app. Unverified means the app supplied its own name.
- You may grant any subset of the scopes, including scopes the client did not ask for, and you may untick any of them.
- A consent request expires 10 minutes after it starts. Finish it in the browser that started it. The consent page warns: If a link or message brought you here and you didn’t start this, deny it.
- Authorization codes are single-use and expire after 120 seconds. Access renews by itself while the connection lasts, which is at most 90 days from approval.
- Only SHA-256 hashes of the opaque 256-bit tokens are stored. Refresh tokens rotate on every use.
- Disconnecting ends a connection. Revoking ends the whole grant. The revocation endpoint is POST /oauth/revoke, following RFC 7009.
WWW-Authenticate: Bearer resource_metadata="https://app.securethread.co/.well-known/oauth-protected-resource/mcp", scope="<scopes>"02
Personal access tokens
A personal access token lets a client that cannot open a browser act as you. Anyone who holds the token acts as you, so use one only for a client you run on your own computer.
- Create the token on the AI access page with your current password. A wrong password counts toward the account lockout limit.
- Choose a lifetime of 7, 30 or 90 days. SecureThread shows the token once, so copy it then.
- A token with the administration scope lasts at most 14 days, so only the 7-day choice applies to it. Creating that token also needs a session that completed two-step verification.
- You can create up to 20 tokens an hour. Revoke a token on the AI access page to stop it at once.
- Changing your password ends your personal tokens and connections.
- Never put a token in a web address or a query string.
Authorization: Bearer <your token>03
Scopes and access levels
A scope is a kind of work an assistant may do. The assistant can do what its granted scopes allow and what the person may do at that moment. SecureThread checks both on every request, so a removed permission or a changed role takes effect on the next request.
- A connection that asks for no scope gets the View and Write drafts levels, which are the read and compose scopes.
- Scopes never widen what the person may do. Services still check ownership, and a record the caller may not see returns NOT_FOUND.
- Administrative permissions count only with the admin scope, approved from a session that completed two-step verification.
read
What the assistant may do
compose
What the assistant may do
send
What the assistant may do
templates
What the assistant may do
contacts
What the assistant may do
mailboxes
What the assistant may do
schedules
What the assistant may do
campaigns
What the assistant may do
workflows
What the assistant may do
analytics
What the assistant may do
approvals
What the assistant may do
admin
What the assistant may do
04
Tools
The server offers 66 tools. Every tool has a title, a description of its effects, a strict input schema and an output schema. The list each person sees depends on the scopes they approved and on their permissions.
- Tools that change data say so in their description. Cancelling a queued email, a schedule or a workflow run cannot be undone.
- Tools that start a send, a schedule or a workflow run are approval-bound. They return a pending result with an approval link.
- Read-only tools also back read-only resources. Drafting prompts create drafts and never send.
- Provider credentials, OAuth refresh tokens, session secrets and credential keys are never returned by any tool, resource or prompt.
- Each tool call writes an audit event with the tool, outcome, error code, the connection and duration. Arguments and results are never recorded.
read
Tools
mailboxes
Tools
templates
Tools
compose
Tools
send
Tools
contacts
Tools
schedules
Tools
campaigns
Tools
workflows
Tools
analytics
Tools
approvals
Tools
approvals or send
Tools
admin
Tools
05
Send requests and approvals
When an assistant asks to send email, SecureThread creates a send request. The request stores the exact recipients, subject, message, attachments and mailbox. The assistant gives you a link to it, and the decision is made in the app.
- The send tool returns pending_confirmation with an approval link. Give the link to the person.
- Approve and send checks the stored request against every sending rule under the person’s session. If the request no longer matches what the page showed, SecureThread refuses it.
- Declining a request sends nothing. A request expires 24 hours after the assistant asked, and an expired request never sends.
- An assistant can withdraw its own waiting request, and can void a pending request with the approvals or send scope. An approved, rejected, withdrawn, declined or expired request cannot be voided and returns CONFLICT.
- Every send needs an idempotencyKey. The same key with the same arguments replays the earlier result. The same key with different arguments returns IDEMPOTENCY_CONFLICT.
- Scheduled sends and workflow runs an assistant starts wait for a person. An assistant can only create campaign drafts and pause a sending campaign. Launching campaigns stays in the app.
- No tool approves or rejects anything. Disconnecting an assistant declines the send requests it left waiting.
- Automatic sending is off by default. When an administrator turns it on, only a reviewed shared template filled in with its variables, sent from the person’s own mailbox, with no attachments and within the allowed number of recipients, can go out without approval.
- The approval page lists why a send needs a person, such as recipients outside the organization, a contact group, attachments, a mailbox the person does not own, or links that hide where they go.
- A message that a mailbox provider has already accepted cannot be recalled.
06
Results and error codes
Every tool returns the same envelope, both as structured content and as its single text block. Results that can carry other people’s text begin with a notice that marks that text as data, not instructions.
- success is false with data and no error when a result is pending, for example while it waits for a send approval, a schedule approval or a template review.
- Failures put a code in error.code. The codes are AUTHENTICATION_REQUIRED, PERMISSION_DENIED, NOT_FOUND, CONNECTION_NOT_FOUND, PROVIDER_REAUTH_REQUIRED, PROVIDER_UNAVAILABLE, VALIDATION_ERROR, CONTENT_REJECTED, APPROVAL_REQUIRED, RATE_LIMITED, QUOTA_EXCEEDED, SENDING_DISABLED, IDEMPOTENCY_CONFLICT, CONFLICT and INTERNAL_ERROR.
- NOT_FOUND also covers anything the caller may not see, so a hidden record never returns 403.
- RATE_LIMITED includes retryAfterSeconds. VALIDATION_ERROR includes per-field details.
- INTERNAL_ERROR returns generic text. The cause is logged with the request ID and is never echoed back.
- Protocol-level failures use the JSON-RPC error codes -32700, -32600 and -32601.
- Long text is paged with offset and nextOffset. Most lists take page and pageSize, up to 25 items a page. Some lists, such as drafts, contact groups and send attempts, allow up to 50.
- The securethread://guide resource explains each error code to assistants.
{ success, data?, error?: { code, message, details?, retryAfterSeconds? }, summary?, nextAction?, notice? }07
Connect each app
Each app needs AI assistant access turned on, and your role must allow AI assistants. The steps below follow each app’s public setup documentation, and they change when an app changes its menus. After connecting, check that the connection appears on the AI access page.
- Claude on the web or desktop: in Claude’s connector settings, add a custom connector, name it SecureThread and paste the endpoint address. Leave the OAuth fields under Advanced settings empty, choose Connect, then approve on the SecureThread consent page. Claude returns to https://claude.ai/api/mcp/auth_callback, which SecureThread accepts.
- Claude on Team and Enterprise plans: an owner may need to add the connector for the organization first. Each person then connects for themselves.
- ChatGPT: whether your plan and workspace allow a custom MCP server is set by ChatGPT, and its menus change often. Create a custom server with the endpoint address and OAuth sign-in. ChatGPT opens SecureThread so you can approve the connection.
- Cursor: add the server to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project, as in the example. Open Cursor’s MCP settings and find securethread. If Cursor asks you to sign in, follow the prompt. It opens SecureThread so you can approve the connection.
- VS Code: add a server with type http and the endpoint address to .vscode/mcp.json in the workspace, or to your user MCP configuration. Start the server from that file or from the MCP servers view. VS Code asks you to sign in and opens SecureThread so you can approve.
- Claude Code: run claude mcp add --transport http securethread https://app.securethread.co/mcp. Then run /mcp, choose securethread and authenticate. The callback is an address on your own computer, localhost or 127.0.0.1, on any port.
- Other clients: any client that supports remote MCP servers over Streamable HTTP with OAuth 2.1 can use the endpoint. A client that cannot open a browser can use a personal access token, but never put that token in a shared or organization-wide configuration.
{ "mcpServers": { "securethread": { "url": "https://app.securethread.co/mcp" } }}08
Limits and known limitations
Limits apply per connection, per person and per network address. They are listed here so you can plan retries and batch sizes.
- The server is stateless. It keeps no session between requests and sends no messages on its own. GET and DELETE requests answer 405.
- The older HTTP+SSE transport is not supported. Use the endpoint address with Streamable HTTP.
- Browser requests from a web page on another origin are refused with 403.
- Custom-scheme callbacks such as cursor:// are refused. A client whose only callback is a custom scheme cannot connect.
- Only RFC 8414 authorization server metadata is served. An OpenID discovery document is not.
- An authorization code cannot be retried. Reusing one revokes the grant, so the person must connect again. A rotated refresh token works once more within 60 seconds, if its successor was never used.
- While AI access is off, every assistant is refused and existing tokens stop working. The person must connect again after access is turned back on.
- Anyone can register a client while AI access is on, and client names are self-asserted. Before you approve, check the Verified or Unverified label, the return address and the address the connection will act as.
- Request bodies are size-limited and answer 413 when too large. A body that is not JSON answers 415.
Protocol revisions
Value
Requests to the endpoint
Value
Tool calls
Value
Send requests
Value
Personal access tokens
Value
Requests without a working token
Value
Consent request
Value
Authorization code
Value
Connection
Value
Result size
Value
List size
Value
FAQ
Questions, answered
Which assistants can connect?
Any client that supports remote MCP servers over Streamable HTTP with OAuth 2.1 can use the endpoint. Setup steps for Claude, ChatGPT, Cursor, VS Code and Claude Code are on this page.
Has each app been tested with SecureThread?
Not yet with the apps themselves. SecureThread’s tests run the protocol with the official TypeScript SDK client against a real application, database and cache. Setup steps follow each app’s public documentation, so check the connection on the AI access page before you rely on one.
Can an assistant send an email without asking me?
Only when your organization turns on automatic sending for narrow, low-risk emails. Scheduled sends and workflow runs always wait for a person, and an assistant cannot change that setting.
Can an assistant approve its own requests or change settings?
No. No assistant can approve or reject anything, publish a shared template, invite people, change roles or change organization settings. Those actions stay in the app.
What happens to a connection when access changes?
Access is checked on every request, so removing a permission or changing a role takes effect on the next request. Changing your password ends your personal tokens and connections. Turning AI access off for the organization refuses every assistant at once.
Build on SecureThread
Create a workspace key, send from a published template, and get signed events back. Every API send passes the same checks and approvals as one from the app.