Connect an MCP client¶

Outcome¶

You will connect an AI client to one Threadory project and use that project's knowledge without copying a token into chat or documentation.

Before you begin¶

You must have a project role; read-only MCP works for viewer as well as higher roles.
Use a client that supports remote MCP over Streamable HTTP.
Prefer browser OAuth for an interactive client. A headless or CI client needs a project API key created by an administrator.

Each project is a separate MCP connection. Its URL carries an address unique to that project, so never reuse a URL from another project.

The address is a generated string such as p-7m3k9q2xvz, not the project name. A hostname is sent unencrypted with every connection, so it deliberately says nothing about you or your work. It never changes: a connector added once keeps working, including after the project is renamed. Settings → MCP shows the address next to the connection URL.

Use the shared address¶

Threadory also has one address that works for everyone: https://mcp.threadory.ai/mcp. Sign in with your Threadory account and the connection is bound to the project Threadory selects for you. By default that is the project where you hold the highest role, the oldest membership winning a tie; a default pinned by your deployment, or a project you chose on an older version of the sign-in screen, takes precedence. There is no such screen today. If you have a single project, that is simply it. Authorization is unchanged: every call is checked against your current membership and role, and access to another project is never granted by this address.

To be sure which project a client reaches when you belong to several, use that project's own address from Settings → MCP (described above) instead. Add one connection per project.

Pick the way that matches your client:

Claude Code. Run the command, then run /mcp in Claude Code and follow the browser prompt:

claude mcp add --transport http threadory https://mcp.threadory.ai/mcp

Cursor. Open this link in a browser or paste it into the address bar, then review the entry Cursor shows:

cursor://anysphere.cursor-deeplink/mcp/install?name=threadory&config=eyJ1cmwiOiJodHRwczovL21jcC50aHJlYWRvcnkuYWkvbWNwIn0=

VS Code. Open this link the same way:

vscode:mcp/install?%7B%22name%22%3A%22threadory%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.threadory.ai%2Fmcp%22%7D

Any other client. Add this to its MCP configuration, or paste the address into its remote-server dialog:

{
  "mcpServers": {
    "threadory": {
      "url": "https://mcp.threadory.ai/mcp"
    }
  }
}

The same buttons and the list of tools the server exposes are on the public page at https://threadory.ai/mcp. Install links open the client with the entry filled in; you still sign in afterwards.

Connect Claude with OAuth¶

In Threadory, select the project.
Open Settings → MCP.
Under Connection URL, select Copy.
In Claude, open Settings → Connectors → Add custom connector.
Paste the URL and continue.
Authenticate in the browser when prompted.
Return to Claude and ask it to count or find a non-sensitive item in the project.

The One-click install section can open Claude's connector settings directly. It does not remove the OAuth sign-in step.

Connect Cursor or VS Code¶

Open Settings → MCP for the intended project.
Under One-click install, select the button for Cursor or VS Code.
Review the client-generated server entry before accepting it.
Complete browser authentication if the client requests it.
Start a new client session if the tools do not appear immediately.

Configure another client¶

Confirm that the client supports remote HTTP MCP servers.
Copy Manual config (mcp.json) from Settings → MCP.
Paste it into the client's MCP configuration.
Keep the generated server name and project URL together.
Follow the client's authentication prompt and test a read-only request.

The displayed JSON is suitable for clients such as Claude Code, Cursor, and Windsurf that accept an mcpServers configuration. Client file locations and reload behavior differ, so use that client's documentation for the final installation step.

Headless clients and API keys¶

Ask an administrator to open Settings → API Keys.
Create a key with a name that identifies its owner and purpose.
Copy the plaintext value immediately; it is shown only once.
Store it in the client's secret store or protected CI variable.
Send it as the client's bearer credential. Do not add it to the connection URL, repository, screenshots, logs, or prompts.
Revoke the key when the client is retired or the value may have leaked.

OAuth access follows the user's project membership. MCP reads are available to project members; write-capable tools remain restricted by the effective role and credential scopes. The server also verifies that the selected project matches the credential.

Verify the result¶

The client lists Threadory knowledge tools without an authentication error.
A simple read returns data only from the selected project.
A cited-answer tool returns source references that can be opened in Threadory.
A viewer credential cannot perform graph writes.

Common problems¶

Symptom	Likely cause	What to do
`401` or authentication loop	OAuth was not completed, expired, or the client cached an old session	Remove the client connection, add it again from the current URL, and complete browser sign-in
`403`	You are not a member of the URL's project, or the tool exceeds your role	Confirm the active project and ask its administrator to review membership
Tools from two projects conflict	The same connection was reused	Add one separately named MCP connection per project
Client does not accept the config	It does not support remote Streamable HTTP or uses another schema	Use its remote-MCP instructions; do not convert the URL into a local command
API key no longer works	It was revoked or copied incorrectly	Create a replacement; plaintext cannot be recovered from Threadory
A write tool is denied	The credential is read-only or lacks the required scope	Keep read-only access when sufficient; ask an administrator before granting broader access

Next step¶

Use search and cited answers in the web interface, or review the role permissions.