Connect over MCP · Roko Platform Docs

MCP primer

MCP, the Model Context Protocol, lets an agent use a system that is not on your computer, such as Roko Platform. The platform runs an MCP server. You connect your agent to it once, and the connection stays for every later session.

Your computerYour agent

Claude Code, Codex CLI, Copilot CLI, or a desktop app.

MCPas you

Roko PlatformMCP server

Serves the platform's tools.

What you can seeYour projects

Working model
Change requests
Prototypes

The platform's tools appear in your agent's session. The agent acts as you, so it can see and change only what you can.

The server address

Every deployment of the platform has its own address. The MCP server is at /api/mcp under it:

<your-roko-url>/api/mcp

The page in the platform shows the full server address with a copy button. Once you set your platform address, the commands on this page contain it. Until then, replace <your-roko-url> in each command with the address you open the platform at.

Two ways to authenticate

Either way, the agent acts as you and sees only what you can see.

Personal access token (PAT). The client sends the token as a bearer header. It works with every client, including ones that cannot open a browser. Create the token on the project's Settings → You page, under API token. The platform shows it only once, so copy it right away. The token starts with rk_. In the commands below, replace rk_your_token with your token.
OAuth in the browser. A client that supports OAuth opens the platform's consent screen. You sign in with your platform account and approve the app once. To withdraw an app later, open the project's Settings → You page and find Connected applications.

In the terminal

Use this route for an agent that runs in your terminal. Foundational tooling shows how to install one.

Your agent

Add the server for your user, with your token, so it works in every folder:

claude mcp add --transport http --scope user \
  roko <your-roko-url>/api/mcp \
  --header "Authorization: Bearer rk_your_token"

Without --scope user, the server exists only in the folder you ran the command in.

To use OAuth instead, add the server without the header, then start claude, type /mcp, pick roko, and choose Authenticate. Approve the request in the browser:

claude mcp add --transport http --scope user roko <your-roko-url>/api/mcp

To remove the server, run claude mcp remove roko.

Add the server and your token to ~/.codex/config.toml:

[mcp_servers.roko]
url = "<your-roko-url>/api/mcp"
http_headers = { Authorization = "Bearer rk_your_token" }

Start codex and type /mcp: the row for roko reads connected.

To use OAuth instead, add the server with the command below. Codex opens a sign-in link in the browser; approve the request. To authorize a server you added by hand, run codex mcp login roko.

codex mcp add roko --url <your-roko-url>/api/mcp

Add the server once, under one name. Codex Desktop reads the same server list, so a second entry for the same address gives the agent two identical sets of tools, and it can call the one that was never signed in. To remove the server, run codex mcp remove roko.

Copilot CLI signs in with a personal API token. Add the server, with your token in place of rk_your_token:

copilot mcp add --transport http roko <your-roko-url>/api/mcp --header "Authorization: Bearer rk_your_token"

Copilot does not fetch MCP prompts or resources, so it reads the platform's skills and prompts through tools instead. To put the platform's guidance in the system prompt, start Copilot with --allow-all-mcp-server-instructions. The server works without it.

The signed-in GitHub account needs a Copilot plan. Without one, Copilot skips every third-party MCP server.

In a desktop app

A desktop app signs in through the browser. You do not need a terminal or a token. This route connects the app, and it installs no coding agent.

Claude Desktop and claude.ai

Both connect to the platform through a custom connector. First, an owner of your Claude organization adds the platform as a custom connector, under Settings → Connectors → Add custom connector, with the name Roko and the server address. This happens once for everyone. A member who tries to add it is told to ask an owner.

Once the connector exists:

Turn it on
Open Settings, then Connectors, and turn on the Roko connector.
Approve access
Sign in with your platform account and approve access. The approval covers only you.
Check it
Run the connection check.

Codex Desktop

Add the server
Open Settings, then Plugins, then MCP, and choose Add. Give the server a name, and enter the server address.
Approve access
Codex opens the consent screen. Sign in with your platform account and approve the request. The server then reads as connected in the same MCP list.
Check it
Run the connection check.

Add the server once, under one name. The Codex CLI reads the same server list. To withdraw access, disconnect the app in the platform under Connected applications, not in Codex. That also ends any session already running under it.

Check the connection

Ask your agent to call whoami:

PromptCheck the connectionpaste into your agent

Call the whoami tool and tell me which account you are acting as.

If it answers with your own name, you are connected. If it says it has no such tool, the connection failed.

Common errors:

The agent has no whoami tool. The server was not added, or it was added for another folder. In Claude Code, add it again with --scope user.
Unauthorized. The token is wrong, revoked, or replaced by a newer one. Sign in again, or create a new token.
No project <client>/<project>. You are not a member of that project, or the slug is wrong. Ask a project member to add you.
Two sets of platform tools. The server was added twice under different names. Remove one entry.

Name the project, every time

Your agent can see every project you belong to, and it cannot guess which one you mean. Start every session with this line:

PromptOpen every session with thispaste into your agent

I'm working in Roko Platform project <client> / <project>.

Replace the client and the project with your own.