Connect an AI assistant (MCP)

Subcontext has an MCP server, a single address that AI assistants such as Claude, ChatGPT and Codex connect to. Once connected, your assistant can use the same tools as the assistant in the Subcontext dashboard. You ask in plain English, and it looks up leads, conversations, products and policies, and makes changes if you allow it.

MCP (the Model Context Protocol) is the open standard most AI assistants use to connect to other services.

The address, for every assistant:

https://subcontext.com/mcp

There's no key or password. The first time an assistant connects, it opens Subcontext in your browser, where you sign in as yourself and choose what it may do.

What it can do#

The assistant acts as you, with your role, in the organisations you pick and only in the areas you grant. It can't do anything you couldn't do in the dashboard. If you leave an organisation, the assistant loses access to it too.

It can work with almost everything in Subcontext: products, journeys and releases; applications, quotes, policies and claims; your AI agents, channels and conversations; leads in the CRM; and your organisation's settings. The MCP tool reference lists every tool, by permission group, with its arguments.

• Changes aren't confirmed by Subcontext. The assistant in the Subcontext dashboard asks you before each change; an outside assistant doesn't have to (most ask you themselves before using a tool). Choose Read only if you only want answers.
• Product changes are drafts until you publish. Changes to products, covers, journeys, documents and the like only reach customers when a release is published, as in the dashboard.
• Your account must be in good standing. If your organisation's subscription lapses, the assistant can't reach it.

Claude (desktop app and claude.ai)#

1. In Claude, open Settings > Connectors and choose Add custom connector.
2. Name it "Subcontext" and paste https://subcontext.com/mcp as the address.
3. Choose Connect. Your browser opens Subcontext. Sign in and approve access (see The consent screen).
4. In a new chat, turn the Subcontext connector on and ask a question, for example "Which of my leads are due a follow-up today?".

On Claude's Team and Enterprise plans, an owner of your Claude workspace may need to add the connector first.

ChatGPT#

ChatGPT connects to MCP servers as custom connectors (apps), which need developer mode:

1. In ChatGPT, open Settings > Apps & Connectors > Advanced and turn on Developer mode.
2. Choose Create, name it "Subcontext" and paste https://subcontext.com/mcp.
3. Choose OAuth as the authentication, and save. ChatGPT opens Subcontext for you to sign in and approve access.

ChatGPT's menus change from time to time. If yours look different, look for adding a custom connector or MCP server in ChatGPT's own help.

Claude Code#

Add the server from your terminal:

claude mcp add --transport http subcontext https://subcontext.com/mcp

Then start Claude Code, type /mcp, choose subcontext and Authenticate. Your browser opens Subcontext to sign in and approve access.

Codex#

Add Subcontext to the Codex config file (~/.codex/config.toml):

[mcp_servers.subcontext]
url = "https://subcontext.com/mcp"

Then sign in:

codex mcp login subcontext

This opens Subcontext in your browser to approve access. The exact steps can differ between Codex versions, so check Codex's own MCP instructions if yours looks different.

Other assistants and editors#

Any assistant or code editor that supports remote MCP servers with OAuth sign-in can connect the same way. Give it https://subcontext.com/mcp (sometimes called a "Streamable HTTP" or "HTTP" server), and sign in when it asks. It discovers the rest of the setup itself. If it asks for a client id or secret, leave them empty, because it registers itself.

The consent screen#

When an assistant connects, Subcontext shows a page saying the assistant "wants to access your Subcontext account", with the address it will send you back to. Check the name is the assistant you expected. Then choose:

• Access level: Read only (it can look things up but never change anything) or Read & write (it can also create and change things in the areas you grant).
• Access to grant: the areas of Subcontext it may use. Tick a whole area, or open Fine-tune under it to pick individual groups of tools. You must tick at least one.
• Organisations it may act in: if you belong to more than one, tick each one it may work in.

Press Approve access to connect it, or Deny to refuse.

The areas are:

Areas that touch money and customers' personal details start unticked. Each group under Fine-tune is listed, with all of its tools, in the MCP tool reference.

Scopes#

Each choice on the consent screen is an OAuth scope:

• read and write are the access level. Read only grants read; Read & write grants both. Tools that change things need write.
• Each group of tools has its own scope, such as products, crm or conversations. A tool can only be used if its group was granted.

An assistant can ask for particular scopes when it connects. The consent screen then offers only those, and you can still untick any of them. Most assistants don't ask for any, and you're offered everything.

Disconnecting#

Every assistant you've connected is listed under Connected apps. To see them, open your profile and press Manage next to Connected apps. Each shows the organisations it can act in, when it connected, and what it can do.

Press Disconnect to remove one. It stops working straight away. To use it again, connect it from the assistant and approve access again.

An assistant also stops working in an organisation when you leave it, and a connection that hasn't been used for about a month has to be connected again.

What's logged#

• When you approve an assistant, Subcontext sends you a security notification ("New application connected"), and records the approval in the Activity log of each organisation you granted.
• Changes the assistant makes are made as you, so they're recorded the same way as changes you make in the dashboard.
• Each call the assistant makes is also recorded in the API logs of the organisation it acted in. When a connection covers more than one organisation, a call that doesn't act in any of them (such as listing your organisations or finding tools) isn't in any organisation's API logs.

If you get a notification about an assistant you didn't connect, disconnect it under Connected apps and change your password.

For developers: connecting your own client#

If you're building your own MCP client or agent, it connects like any MCP client that follows the specification's authorisation rules. Most MCP libraries handle all of the following once you give them the address.

• Transport: Streamable HTTP at https://subcontext.com/mcp. Send JSON-RPC with POST. Responses are plain JSON with no event stream. There are no sessions, because every request carries its own token.
• Discovery: a request without a token gets 401 with a WWW-Authenticate header pointing to https://subcontext.com/.well-known/oauth-protected-resource/mcp. That names the authorisation server, whose details are at https://subcontext.com/.well-known/oauth-authorization-server.
• Registration: register your client at https://subcontext.com/oauth/register (dynamic client registration). Send a client_name and your redirect_uris (up to 10; https:// addresses, or http://localhost and http://127.0.0.1 for apps on the user's computer). Leave token_endpoint_auth_method out for a public client, or use client_secret_post to get a secret. Registering grants nothing on its own. Every token still needs a person to approve it.
• Sign-in: the authorization code flow with PKCE (S256 only), at https://subcontext.com/oauth/authorize and https://subcontext.com/oauth/token. Send resource=https://subcontext.com/mcp to both, including when refreshing. A request without it is refused.
• Scopes: a client registered with read write (the default) lets the person choose either access level; one registered with read alone can only ever read. When you sign someone in, add group scopes (the scope shown on each group in the tool reference) to offer only those groups.
• Tokens: an access token lasts two hours. Use the refresh token to get a new one. A refresh token that hasn't been used for 30 days after its access token expired is refused, and the person has to approve access again.

A registration looks like this:

curl -X POST https://subcontext.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Our assistant", "redirect_uris": ["http://127.0.0.1:8765/callback"], "scope": "read write"}'

Once connected, the server offers a small set of tools straight away: the everyday lookups, and four tools for finding and running the rest (list_tool_groups, search_tools, describe_tools and use_tool). This keeps the list your model has to read short, however many groups were granted. See Always available.

This is different from the access tokens your own systems use for the Subcontext API, which don't involve a person and can't use the MCP server.

Need help?#

Email hello@subcontext.com.