Thread MCP Server: Developer Guide

Availability: generally available to all partners. If you don’t see the connector URL in Thread (below), ask your admin or your Thread account team.

Looking for the other direction? This guide is about using Thread’s tools from your own agent. To bring external tools (Linear, Notion, Zapier) into Super Magic, see Add External Tools to Super Magic with Connectors.

Overview

Thread exposes its service-desk actions over the Model Context Protocol, so any MCP-capable client — Claude Desktop, ChatGPT, Claude Code, Cursor, partner agents, your own app — can drive Thread workflows the same way Super Magic does in-product: search tickets, look up clients and devices, and (with the right permissions) take real actions.

Endpoint:   <https://api.getthread.com/mcp>
Transport:  Streamable HTTP
Auth:       OAuth 2.1 — sign in with your Thread account (no tokens to manage)

https://api.getthread.com/mcp/thread is a supported alias for the same server — use it if a client’s connector directory already has a “thread” entry, or to keep the name unambiguous when you connect multiple MCP servers.

Once connected, you can ask your assistant to do real work in Thread:

“Create a ticket for Acme Corp: user can’t print, high priority.”

“Show my open tickets for Globex.”

“Add a note to ticket 12345 and log 30 minutes.”

“Look up the contact Jane Doe and her recent tickets.”

“Search our knowledge base for the VPN setup article.”

The assistant acts as you: it can only see and do what you can in Thread, in your workspace.

Before you start

A Thread account with login access.
MCP enabled for your workspace. The tell: in Thread’s Inbox, open Settings → Connectors → Thread MCP access: if the connector URL isn’t shown, ask your admin or Thread account team.

Get your connector URL

In Thread’s Inbox: Settings → Connectors → Thread MCP access → copy the URL under “Add this URL as a custom connector”:

<https://api.getthread.com/mcp>

Connect your client

Claude Desktop
ChatGPT
Claude Code (CLI)
Other clients (Cursor, …)

Add a custom connector

Settings → Connectors → Add custom connector

Paste the URL

Paste the connector URL and click Add, then Connect / Log in

A browser window opens — sign in with your Thread account and approve

Finish

Done — Thread’s tools appear in Claude. No token needed.

claude mcp add --transport http --scope user thread <https://api.getthread.com/mcp>

On first use, Claude Code opens a browser to sign in with Thread (or run /mcp inside Claude Code to authenticate). --scope user makes it available in every project; drop it to add Thread to the current project only. Remove later with claude mcp remove thread.

Microsoft Copilot: two different products, one supported

Microsoft ships two Copilot products that both let you connect an MCP server, and they look similar enough to mix up. Only one of them works with Thread MCP today.

Microsoft product	Supported with Thread MCP?	What it asks for at setup
Copilot Studio (the agent builder)	Yes: use this today	Just the Thread MCP URL. Sign in with a Thread account when prompted.
Microsoft 365 Copilot custom federated connectors	Not yet	A Reference ID and OAuth Client ID / Secret issued by the MCP server. Thread doesn’t issue these.

Connect Copilot Studio to Thread MCP

Copilot Studio is Microsoft’s low-code agent builder. Add Thread MCP as a tool on the agent that should use it:

Open the agent's Tools tab

In Copilot Studio, open the agent you want to give Thread access to, then open its Tools page.

Add a new MCP tool

Select Add a tool → New tool → Model Context Protocol. Copilot Studio’s MCP onboarding wizard opens.

Fill in the server details

Server name: Thread. Copilot Studio turns this into a Power Platform custom connector, so the name has to be unused in the environment. Keep it to plain words: no periods, and no version numbers like Thread 2.0.
Server description: a short line the orchestrator uses to decide when to call Thread, for example: Thread service-desk actions: search and update tickets, look up clients and contacts, log time.
Server URL: https://api.getthread.com/mcp
Transport: Streamable HTTP (Copilot Studio’s default)

Set Authentication to OAuth 2.0, Dynamic (with discovery)

Select Authentication → OAuth 2.0, then set Configuration type to Dynamic (with discovery). That is the whole configuration: Thread’s MCP server publishes OAuth 2.1 discovery metadata and supports dynamic client registration, so Copilot Studio finds the endpoints and registers itself at creation time.Leave every credential field empty, and do not choose Manual. Manual asks for a Reference ID, Client ID, and Client Secret that Thread does not issue. Microsoft describes all three configuration types in Configure OAuth 2.0 authentication.

Create the connection and sign in with Thread

Select Create, then Next. On Add tool, select Create a new connection. A browser window opens: sign in with your Thread account, approve, then select Add to agent.

Add the tools you want to expose

Back on the tool’s settings page, Copilot Studio lists every Thread tool your account can see. Leave Allow all on to expose everything, or turn it off to pick individual tools (for example, only reads). Save.

The agent can now call Thread. Ask it something like “Show my open tickets for Acme” to confirm end-to-end.

”Can’t create MCP server. Try again.”

This error fires before Copilot Studio ever contacts Thread. It means Copilot Studio could not create the Power Platform custom connector it builds behind the scenes, so nothing on Thread’s side will fix it. Work through these in order:

Delete the orphaned connector from your last attempt

This is the usual cause, and Microsoft confirms it in this Q&A thread: when MCP onboarding fails partway, the custom connector is still written to Dataverse but never appears in the Copilot Studio UI, and every later attempt collides with it, including attempts under a new name. Open make.powerapps.com, confirm you are in the same environment, then go to Custom connectors and delete anything Thread-shaped. Wait two or three minutes for metadata to sync before retrying.

Simplify the server name

Retry as Thread. A name carrying a period or a version suffix becomes a connector logical name and is a needless risk.

Check your environment permissions

Creating a custom connector needs system administrator rights on the target Power Platform environment. Ask your Power Platform admin to confirm yours, or switch to an environment you own.

Move off the default environment

Tenant-level data loss prevention policies commonly block custom connectors in the default environment, and MCP tools inherit them because Copilot Studio reaches an MCP server through a Power Platform connector. Try a dedicated development environment instead, and see Microsoft’s MCP servers and data policies and Configure a data policy.

Click outside the URL field, then Create again

The wizard sometimes leaves Server URL showing “Enter the complete server path to continue” and the Create button looking disabled when the URL is in fact valid. Click anywhere outside the field, then select Create.

If the server still will not create, switch Configuration type from Dynamic (with discovery) to Dynamic and supply the two endpoints by hand. It is the same registration flow with discovery skipped:

Authorization URL: https://api.getthread.com/oauth/authorize
Token URL template: https://api.getthread.com/oauth/token

Still avoid Manual as a workaround. It requires a client ID and secret preissued by the MCP server, and Thread does not issue per-partner credentials. If a field insists on them, you have hit the same wall as Microsoft 365 Copilot federated connectors below.

Microsoft’s own references for this section:

Connect your agent to an existing MCP server, the onboarding wizard end to end, including supported transports and Configure OAuth 2.0 authentication.
Add MCP tools and resources to your agent, for picking which Thread tools the agent may call.
Adding MCP servers as a tool fails, Microsoft’s Q&A thread on orphaned custom connectors.
Configure a data policy, if your environment blocks custom connectors.

Microsoft 365 Copilot federated connectors (not yet)

Microsoft 365 Copilot custom federated connectors is a different product — it makes an external data source searchable inside Microsoft 365 Copilot. Its setup dialog for an MCP endpoint asks for:

A Reference ID: an id from a Microsoft-side OAuth or SSO registration in the Teams Developer Portal.
An OAuth Client ID and Client Secret: credentials the MCP server issues to the connector.

Thread MCP does not issue per-partner client IDs or secrets, and doesn’t have an entry in Microsoft’s Connections Gallery yet. If a partner is being asked for those fields, they’ve landed on the federated connector path — that path isn’t available with Thread today. Use Copilot Studio instead.

Automation keys: connect without a browser (beta)

Beta. Automation keys are rolling out gradually and may not be enabled for your workspace yet. If minting fails with an “MCP automation keys are not enabled” error, ask your Thread account team.

OAuth sign-in needs a browser. Some clients never get one: n8n, CI pipelines, and other server-side automations. For those, Thread supports automation keys: personal access tokens that authenticate against the same MCP endpoint with a static bearer credential instead of a sign-in. Who can mint one:

Any member can mint a key bound to themselves.
Workspace admins can mint a key for any active member in the workspace.
Team admins can mint a key for members on their own teams, but not for workspace admins.

Workspace admins and team admins can mint and revoke keys from Thread Admin: open Admin → Magic AI → MCP keys, select Generate token, then pick the member, name the key, and set an expiry. The page also lists the keys you can manage with each key’s bound member and issuer: every key in the workspace for workspace admins, or keys for members on their teams for team admins. Alternatively, mint a key with a POST to /api/v1/mcp/tokens on Thread’s API, authenticated as the issuing member:

{
  "name": "n8n ticket sync",
  "expires_at": "2027-03-01T00:00:00Z",
  "member_id": 4821
}

name, a label so you can tell keys apart later (required).
expires_at — when the key stops working. Optional for a key bound to yourself, required when minting for another member, and never more than one year out.
member_id, the member the key acts as. Omit it to bind the key to yourself. Sending it without admin rights returns 403.

The response includes the key’s plaintext value (it starts with mcp_) exactly once. Store it in your secret manager — Thread keeps only a hash and cannot show it again. Use the key as a bearer token wherever your MCP client accepts auth headers:

{
  "mcpServers": {
    "thread": {
      "url": "https://api.getthread.com/mcp",
      "headers": { "Authorization": "Bearer mcp_…" }
    }
  }
}

A key behaves exactly like a signed-in connection for its member: same tool list, same permissions, same audit trail. Each key also records which member issued it, so admins can see who minted a key for whom. To revoke a key, send DELETE /api/v1/mcp/tokens/{id} — connections using it stop working immediately. List keys beyond your own with GET /api/v1/mcp/tokens?scope=company: workspace admins see every key in the workspace, and team admins see keys for members on their teams, plus their own. Revoking follows the same scope; a key outside it returns a not-found error.

Permissions: every connection sees a different tool list

The server registers tools per connection, applying exactly the permissions that member has in Super Magic:

Gate	Effect on the tool list
Member role	Intent and flow tools appear only for workspace admins
Workspace plan	On a non-Agentic plan (no AI Pro), the connection sees only the seven read-only Super Magic tools, the same surface Super Magic exposes in the inbox. Write and integration tools appear only on Agentic plans.
Workspace write access level	Write tools (create/update ticket, notes, time, approvals…) appear only if the member passes it (All members / Admins only / Custom list)
Per-tool toggles	A write tool an admin switched off disappears for everyone
Integrations	NinjaOne / ImmyBot / TimeZest / IT Glue / Hudu tools appear only when the integration is configured + enabled. NinjaOne additionally requires the member’s own sign-in

Not every Super Magic tool is exposed over MCP

Thread MCP exposes a curated subset of Super Magic’s tools. Every tool on the MCP server is a Super Magic tool with the same name and the same gating, but the reverse doesn’t hold. Some Super Magic tools never appear over MCP, no matter how the workspace is configured:

Liongard: Super Magic-only, in both forms (the workspace integration and the per-member connector). Connecting Liongard and turning on its Super Magic toggle adds Liongard tools in Inbox chat, but an MCP client will never list them.
Per-member connector tools (Linear, Notion, Zapier) — these register inside Super Magic only.

To use those tools, run the request in Super Magic in Inbox (or a Companion App) instead of your external client. The tool reference is the canonical list of what each surface exposes. Practical consequence: don’t hardcode the tool list. Call tools/list and work with what’s there. A read-only member’s connection registers only read tools; an admin on a fully-integrated workspace can see 50+. The connection only ever touches your workspace’s data.

Typical workflows

Discover ids, then write. Ticket writes take internal ids — resolve them first:

search_clients → client_company_id
list_boards, list_ticket_statuses, list_ticket_priorities → board/status/priority ids
create_ticket / update_ticket / add_ticket_note / log_time_entry with those ids

Look up before acting. search_tickets accepts a PSA ticket number or internal id and returns internal_ticket_id — pass that to write tools. Classify tickets (ConnectWise and HaloPSA): on ConnectWise workspaces, list_board_classifications returns the Type → Subtype → Item tree for a ticket’s board; pass the resolved ids to set_ticket_classification. Passing only item_id sets all three levels without disturbing the existing Type or Subtype — see the tool reference for the full id cascade. On HaloPSA workspaces the same pair works on Category 1: list_board_classifications returns a flat list of Category 1 values, and set_ticket_classification takes type_id alone (subtype_id and item_id are rejected). Device workflows (NinjaOne connected): search_ninjaone_devices → get_ninjaone_device / list_ninjaone_alerts → reboot_ninjaone_device etc. To scope by device type (“all Linux servers”, “every Windows workstation”) pass the device_class parameter instead of putting the OS name in query. query only matches hostname and last-logged-in user, so query: "linux" returns whatever happens to have “linux” in its name, not Linux machines. Admin automation: intent and flow tools let an admin connection inspect and build workspace automations programmatically.

Rate limits

The Thread MCP endpoints (/mcp and /mcp/thread) enforce two layers of throttling. Both apply per minute and use a rolling one-minute window:

Layer	Bucket	Limit
Pre-auth IP backstop	Client IP	1,200 requests / minute
Per-company tenant limit	Workspace (company)	300 requests / minute

PAT and OAuth clients for the same workspace share a single per-company bucket, so mixing auth methods does not raise your effective limit. The Thread MCP bucket is separate from those of Thread’s other integrations, so hitting one server’s limit never affects the other. When you exceed a limit, the server responds with HTTP 429 Too Many Requests and a Retry-After header (in seconds). Wait for that duration before retrying — clients should implement exponential backoff on 429s and honor Retry-After. If you regularly bump into these limits, batch requests where possible, cache lookups like list_boards / list_ticket_statuses / list_ninjaone_organizations locally, and contact your Thread account team about a higher tenant limit.

Security model

You authorize by signing in: no secrets to paste, store, or rotate for the one-click path.
Least privilege by construction: a connection can never do more than its member can in the product. To restrict an external agent, restrict the member.
Disconnect = revoke: remove the connector in your AI client and the connection stops working.
Audit: every tool call is logged under the member identity behind the connection.

Errors & troubleshooting

Symptom	Meaning	Fix
”Your account has no active Thread membership”	Signed into an account that isn’t an active member of a Thread workspace	Sign in with the right account
Tools don’t appear / connection fails	URL typo, sign-in not completed, or stale client state	Re-check the exact URL, finish the sign-in, then quit and relaunch the client
No connector URL visible in Thread	MCP isn’t enabled for your workspace	Ask your admin / Thread account team
Login opens but errors out	Transient auth issue	Retry from a fresh browser session; if it persists, contact Thread support
A tool you expect isn’t in tools/list	Per-connection visibility (matrix above)	Check the member’s role, write access, the tool’s toggle, and integration state
A tool works in Super Magic in Inbox but never appears over MCP	The tool is Super Magic-only: Liongard and per-member connector tools (Linear, Notion, Zapier) are not exposed over Thread MCP	Run that request in Super Magic in Inbox or a Companion App instead
Copilot Studio: “Can’t create MCP server. Try again.”	Copilot Studio could not create its own Power Platform custom connector, usually colliding with an orphaned one from a failed attempt	Work through “Can’t create MCP server. Try again.” above
Copilot Studio asks for a Client ID and Secret	Configuration type is set to Manual, or you are in Microsoft 365 Copilot federated connectors rather than Copilot Studio	Set Configuration type to Dynamic (with discovery); if the fields persist, you are on the federated connector path, which Thread does not support

Tool reference

Full tool-by-tool documentation: Super Magic Tool Reference.

Integrations

Thread Inbox

Messenger

Companion Apps

Voice AI

Magic AI

Magic Agents

Super Magic

Service Intelligence

Magic Analytics

Automation

Workspace administration

Notifications

Security & compliance

Plans & billing

Thread MCP Server: Developer Guide

Overview

Before you start

Get your connector URL

Connect your client

Microsoft Copilot: two different products, one supported

Connect Copilot Studio to Thread MCP

”Can’t create MCP server. Try again.”

Microsoft 365 Copilot federated connectors (not yet)

Automation keys: connect without a browser (beta)

Permissions: every connection sees a different tool list

Not every Super Magic tool is exposed over MCP

Typical workflows

Rate limits

Security model

Errors & troubleshooting

Tool reference

​Overview

​Before you start

​Get your connector URL

​Connect your client

​Microsoft Copilot: two different products, one supported

​Connect Copilot Studio to Thread MCP

​”Can’t create MCP server. Try again.”

​Microsoft 365 Copilot federated connectors (not yet)

​Automation keys: connect without a browser (beta)

​Permissions: every connection sees a different tool list

​Not every Super Magic tool is exposed over MCP

​Typical workflows

​Rate limits

​Security model

​Errors & troubleshooting

​Tool reference

Overview

Before you start

Get your connector URL

Connect your client

Microsoft Copilot: two different products, one supported

Connect Copilot Studio to Thread MCP

”Can’t create MCP server. Try again.”

Microsoft 365 Copilot federated connectors (not yet)

Automation keys: connect without a browser (beta)

Permissions: every connection sees a different tool list

Not every Super Magic tool is exposed over MCP

Typical workflows

Rate limits

Security model

Errors & troubleshooting

Tool reference