Skip to content

Connect a client to Direct over MCP

An MCP client connects to Direct with a personal access token. This page shows how to create the token, configure a client, keep the token safe and fix the common failures. See Tools for what the client can then do.

  • You are an active member of the Direct organization you want to work in. A token only works for an active member.
  • MCP access is turned on for your Direct. If it is not, the MCP address answers 404. Ask whoever runs your Direct.
  • You know your Direct address. The MCP endpoint is the path /mcp on that address, shown below as https://<your Direct address>/mcp. It uses streamable HTTP.
  1. Sign in to Direct and open My profile.
  2. In the Personal access tokens card, type what the token is for in the name box, for example Claude Code on my laptop.
  3. Choose how long it works: 7 days, 30 days or 90 days. A token never works for longer than 90 days.
  4. Under What it may do, select the scopes the agent needs and no more. Read is selected for you.
  5. Select Create token.
  6. Select Copy while the message Copy the token now - it is not shown again. is showing. Direct stores only a hash of the token. If you lose it, revoke it and create another.

The token acts as you, in the organization it was created in.

Option in Direct Scope What it allows
Read direct:read Read work, content and status through the API and MCP.
Write content direct:content.write Draft and revise content as you.
Do work direct:work Start and steer work as you.
Request changes direct:write Admit journeys, file issues and answer questions as you. Never approves a request.

Tools names the scope each tool needs.

Every client sends the token in an Authorization header and your tenant id in an x-cratis-tenant-id header:

Authorization: Bearer <personal access token>
x-cratis-tenant-id: <your tenant id>

Direct refuses a request that has no tenant header, more than one value, or a malformed value. Send no other identity or session headers, such as x-cratis-token-scope: Direct refuses those even beside a valid token. A token’s scopes come from the token itself. If you do not know your tenant id, ask whoever runs your Direct. The examples use the made-up id acme-tenant; replace it with your own.

Put the token in an environment variable and have the client read it from there. The examples use DIRECT_TOKEN. Read it without echoing it so it stays out of your shell history, or load it from your password manager:

Terminal window
read -rs DIRECT_TOKEN && export DIRECT_TOKEN

Add the server to a .mcp.json file. Claude Code expands ${DIRECT_TOKEN} when it reads the file, so the token itself is not in the file:

{
"mcpServers": {
"direct": {
"type": "http",
"url": "https://<your Direct address>/mcp",
"headers": {
"Authorization": "Bearer ${DIRECT_TOKEN}",
"x-cratis-tenant-id": "acme-tenant"
}
}
}
}

Add the server to ~/.codex/config.toml and name the variable that holds the token:

[mcp_servers.direct]
url = "https://<your Direct address>/mcp"
bearer_token_env_var = "DIRECT_TOKEN"
http_headers = { "x-cratis-tenant-id" = "acme-tenant" }

Add the server by hand to ~/.pi/agent/mcp.json, or to .pi/mcp.json in a trusted project. pi expands ${DIRECT_TOKEN} when it reads the file:

{
"mcpServers": {
"direct": {
"url": "https://<your Direct address>/mcp",
"headers": {
"Authorization": "Bearer ${DIRECT_TOKEN}",
"x-cratis-tenant-id": "acme-tenant"
}
}
}
}

Any MCP client that supports streamable HTTP and a static bearer header works. Configure the URL and the Authorization and x-cratis-tenant-id headers as above. A client that can only sign in through a browser cannot connect, because Direct does not run a sign-in for MCP clients.

Ask the client to list its MCP tools. Tool names start with direct_. Read tools such as direct_my_work and direct_knowledge_search need only the Read scope.

  • Never commit a token to a repository, and never put its value in a configuration file you commit. Refer to an environment variable instead.
  • Never paste a token into a prompt or a chat with an agent. The agent does not need to see it; the client sends it.
  • Choose the shortest lifetime and the fewest scopes that work.
  • Create one token per client and machine, so you can revoke one without breaking the others.

Open My profile, find the token in Personal access tokens and select Revoke, then select Yes to confirm. Anything using it stops working. Direct remembers a successful check for up to 60 seconds, so a revoked token can still be accepted for up to a minute. An expired token shows Expired in the list and stops working.

What you see What it means and what to do
404 from the MCP address The address is wrong, or MCP access is not turned on for your Direct. Check the address, then ask whoever runs your Direct.
401 There is no token, or Direct does not accept it: it is mistyped, expired or revoked. Check that DIRECT_TOKEN is set in the environment the client starts from. Create a new token if needed.
401 with no tenant header, or after adding other headers Direct requires x-cratis-tenant-id with exactly one valid value. Add it. If the client adds identity or session headers, remove them and send only Authorization and x-cratis-tenant-id.
403 with insufficient_scope The tool needs a scope the token does not have. The response names it. Create a new token with that scope.
403 with “You are not an active member” A token only works for an active member of the organization. Ask an administrator to invite you, accept the invitation in Direct, then try again.
429 or 503 Direct is checking too many tokens at once. Wait a moment and try again.
The client asks you to sign in The client expects a browser sign-in. Configure the bearer header as shown above.