> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Thread MCP Server: Developer Guide

> Connect Claude Desktop, ChatGPT, Cursor, or any MCP client to Thread's service-desk API via OAuth 2.1 to search tickets, manage contacts, and run write actions.

<Tip>
  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.
</Tip>

<Note>
  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**.
</Note>

## Overview

Thread exposes its service-desk actions over the [Model Context Protocol](https://modelcontextprotocol.io), 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)
```

<Note>
  `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.
</Note>

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

<Tabs>
  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Add a custom connector">
        **Settings → Connectors → Add custom connector**
      </Step>

      <Step title="Paste the URL">
        Paste the connector URL and click **Add**, then **Connect / Log in**
      </Step>

      <Step title="Sign in with Thread">
        A browser window opens — **sign in with your Thread account** and approve
      </Step>

      <Step title="Finish">
        Done — Thread's tools appear in Claude. No token needed.
      </Step>
    </Steps>
  </Tab>

  <Tab title="ChatGPT">
    <Steps>
      <Step title="Add a custom connector">
        **Settings → Connectors → Add custom connector** (custom MCP)
      </Step>

      <Step title="Paste and sign in">
        Paste the URL, add it, and complete the Thread sign-in when prompted
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code (CLI)">
    ```
    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`.
  </Tab>

  <Tab title="Other clients (Cursor, …)">
    Same flow everywhere: add the URL as a custom connector and sign in with your Thread account.
  </Tab>
</Tabs>

## 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:

<Steps>
  <Step title="Open the agent's Tools tab">
    In Copilot Studio, open the agent you want to give Thread access to, then open its **Tools** page.
  </Step>

  <Step title="Add a new MCP tool">
    Select **Add a tool → New tool → Model Context Protocol**. Copilot Studio's MCP onboarding wizard opens.
  </Step>

  <Step title="Fill in the server details">
    * **Server name**: `Thread`
    * **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)
  </Step>

  <Step title="Leave client ID and secret blank">
    Do not paste anything into a Reference ID, Client ID, or Client Secret field. Thread's MCP server uses OAuth 2.1 with dynamic client registration, so Copilot Studio registers itself at connection time — there is nothing for you to preconfigure on Thread's side.
  </Step>

  <Step title="Create the connection and sign in with Thread">
    Save the tool. When Copilot Studio prompts to authorize the connection, a browser window opens — sign in with your Thread account and approve.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Note>
  Microsoft's own reference: [Connect your agent to an existing MCP server](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) and [Add MCP tools and resources to your agent](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-components-to-agent).
</Note>

### 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.

## 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 / TimeZest / IT Glue / Hudu / Liongard / ImmyBot tools appear only when the integration is configured + enabled — and NinjaOne (and per-member connectors like Linear / Notion / Zapier) additionally require the member's own sign-in |

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:

1. `search_clients` → `client_company_id`
2. `list_boards`, `list_ticket_statuses`, `list_ticket_priorities` → board/status/priority ids
3. `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.

**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 Automagically's, 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 |

## Tool reference

Full tool-by-tool documentation: [**Super Magic Tool Reference**](/super-magic/super-magic-tool-reference) .

<Note>
  See **Super Magic** and **Integrations** updates in the [changelog](/changelog/q3-2026).
</Note>


## Related topics

- [Thread MCP, the tool reference, and the API](/start-here/roles/automation-engineer/thread-mcp-and-api.md)
- [Super Magic Admin Guide: Setup, Access & Safety](/super-magic/super-magic-admin-guide-setup-access-safety.md)
- [Super Magic Tool Reference](/super-magic/super-magic-tool-reference.md)