Connect your AI assistant

Takaro exposes an MCP endpoint: one URL your AI assistant connects to. Once connected, it can work with your game servers, players, modules, and roles on your behalf, as you, with exactly your permissions. Claude Code, Codex, Claude.ai and ChatGPT connect with nothing but that URL.

Quick start

Two commands. The first installs the Takaro skill, which teaches your agent the Takaro flows: onboarding a server, modules, bans, roles, the shop, Discord. The second connects the MCP server it acts through.

npx skills add gettakaro/skills

Claude Code

claude mcp add --transport http takaro https://api.takaro.io/mcp

Then run /mcp inside Claude Code, pick takaro and authenticate.

Codex

codex mcp add takaro --url https://api.takaro.io/mcp
codex mcp login takaro

Claude.ai

Settings → Connectors → Add custom connector, URL https://api.takaro.io/mcp. Custom connectors are not on every plan; if you cannot find the option, use Claude Code.

ChatGPT

Add a remote MCP server from ChatGPT’s settings with https://api.takaro.io/mcp. Whether the option is available depends on your plan and, in a workspace, on your admin’s policy.

Cursor

Add the server to mcp.json with the pre-registered client id (see Assistants that need a client id):

{
  "mcpServers": {
    "takaro": {
      "url": "https://api.takaro.io/mcp",
      "auth": { "CLIENT_ID": "takaro-mcp-cursor" }
    }
  }
}

VS Code

Add the server to mcp.json with the pre-registered client id (see Assistants that need a client id):

{
  "servers": {
    "takaro": {
      "type": "http",
      "url": "https://api.takaro.io/mcp",
      "oauth": { "clientId": "takaro-mcp-vscode" }
    }
  }
}

A browser opens on the Takaro login page. Sign in, and a consent screen appears asking whether to let the assistant act on your Takaro account. Approve it. Then check the connection:

list my Takaro domains

It should name every domain you belong to.

Prefer to let the agent do the setup? Paste this into any assistant that supports skills:

Install the Takaro skill with npx skills add gettakaro/skills, connect the Takaro MCP server at https://api.takaro.io/mcp, then help me get my server set up.

The skill lives at github.com/gettakaro/skills. It works in every agent the skills CLI supports; without the CLI, copy skills/takaro/ into your agent’s skills directory.

What you need

• A Takaro account.
• Membership of at least one Takaro domain. An assistant connected to an account with no domain can sign in, but has nothing to act on.
• An assistant that speaks a current version of the MCP protocol (revision 2026-07-28 or newer); an older client is turned away even after signing in successfully.

Which assistant do you have?

Assistant	Status	What you supply
Claude Code	Verified	The URL
Codex	Expected to work, not confirmed by Takaro	The URL
Claude.ai	Expected to work, not confirmed by Takaro	The URL
ChatGPT	Expected to work, not confirmed by Takaro	The URL
Cursor	Unverified	The URL and a client id
VS Code / Copilot	Unverified	The URL and a client id
Windsurf, Zed	Not supported	n/a

“Verified” means somebody has driven the whole flow (sign-in, consent, and real calls) end to end. Everything below that line is honest about what has not been tried yet.

The endpoint

Deployment	URL
Takaro-hosted	https://api.takaro.io/mcp
Self-hosted	<your BASE_URL>/mcp

You never have to look up a login server. The endpoint publishes a discovery document that tells the assistant where to authenticate, and every compliant assistant reads it automatically. Adding the server does not sign you in; that is the separate login step above. To disconnect and start over in Claude Code: claude mcp remove takaro.

Assistants that need a client id

Claude Code, Codex, Claude.ai and ChatGPT register themselves with Takaro automatically, using their vendor’s published identity. Cursor and VS Code do not. For those, Takaro pre-registers a client in every environment, and you point the assistant at its fixed client id:

Assistant	client_id
Cursor	takaro-mcp-cursor
VS Code / Copilot	takaro-mcp-vscode

Everything else (consent, permissions, scopes) is already configured on Takaro’s side.

Unverified

Neither of these has been driven through the whole flow against Takaro, so we cannot promise it works. Both vendors document a client-id setting on an MCP server entry (Cursor as auth.CLIENT_ID, VS Code as oauth.clientId), but check your own version’s documentation for the current name. If your assistant has no such setting, it is not supported yet: it will try to register itself, which Takaro refuses. Either way, please open an issue telling us what you found; it is exactly what we are missing.

Self-hosting, or curious about the details? Both clients are defined in containers/keycloak/config/takaro-realm.yaml, including the exact redirect URIs they accept.

Not supported yet

Windsurf and Zed have no client. Neither publishes a fixed callback URL anywhere authoritative, and Takaro will not guess one: a redirect URI that is not exactly right is a security hole rather than a convenience.

More generally, an assistant that registers itself by URL can only do so if its own host is on Takaro’s allowlist. claude.ai, chatgpt.com and loopback addresses are allowed today. On Takaro-hosted, open an issue to ask for a host to be added. On a self-hosted deployment you add it yourself. See Self-hosted deployments.

What your assistant can and cannot do

Your assistant acts as you: same roles, same permissions, as described in roles and permissions. It works in one domain at a time: a domain is one tenant, and its game servers, players, modules, and roles are separate from every other domain’s. Staff-only operations, such as creating domains, are excluded from what it can see or call at all. Whatever an action records in your event log when you do it in the dashboard, it records the same way when your assistant does it (with your user as the acting user), and your normal rate limits apply.

It has four tools:

Tool	What it does
search_api	Finds API operations from a plain-language description, and returns their ids with destructive and deprecated flags
describe_operation	Returns the exact request and response shape of one operation, including validation rules
call_api	Runs one operation as you, and returns the response
list_domains	Lists the domains you belong to, with their names and ids

A well-behaved assistant searches, describes, then calls, and both the server and the tool descriptions tell it to. The Takaro skill adds what the tools cannot: which operations make up a flow, in what order, and how to check the result.

Choosing a domain

If you belong to one domain, there is nothing to do: the assistant never mentions domains and never asks.

If you belong to several, a call that does not name a domain is refused before it runs, with a message listing each domain by name and id and telling the assistant to ask you which one to use. Tell it, and it repeats the call against that domain. This is deliberate: guessing wrong and acting on the wrong domain is worse than asking.

If you belong to none, every call is refused, because there is nothing to act on.

The destructive-call brake

Takaro limits how fast an assistant can delete things. By default, the sixth delete within 60 seconds is refused, with a message telling the assistant to stop, ask you what should be deleted, and try again after the window. The window starts at the first delete and is not extended by later ones.

Deletes are counted per user across all your domains, and attempts count: a delete Takaro then rejects for another reason still spends one. Creating and updating are never braked, only deleting (and any operation Takaro explicitly marks as destructive). Reading keeps working while the brake is engaged: it stops runaway deletion, it does not lock your assistant out. The brake applies only to the MCP endpoint, never to the REST API.

Large responses

Two rules keep an answer inside a model’s context window:

• A paginated operation called without a page size is given a small one automatically, so “list the players” does not return thousands of rows.
• A response larger than 64 KB is cut off, and a --- TRUNCATED --- note is appended saying how large the response really was and how to fetch the rest: a smaller page size, the next page, or a narrower filter.

If your assistant reports that data was truncated, that is not an error. Ask it to narrow the query.

Revoking access

Removing the MCP server from your assistant stops that assistant using it, but it does not withdraw the permission you granted on the consent screen. To do that, open the account console of the login server your browser was sent to during setup (its address is the one you saw in the browser while signing in) and remove Takaro’s entry under Applications. Signing out of every session there ends any access token already issued.

Do both if you have lost the device the assistant was running on.

Troubleshooting

The assistant says it cannot reach Takaro, or reports a 401

The token is missing, expired, or was issued for something other than the Takaro API. Remove the MCP server from your assistant and add it again so the login runs afresh. In Claude Code, run claude mcp remove takaro followed by the claude mcp add command above.

The browser opened but the login page never loaded

Self-hosted deployments only. The login server has to be reachable from the machine running the browser, over HTTPS, on a public hostname. An internal-only address dead-ends here even though the API itself works.

No consent screen appeared, and the connection failed

The assistant’s host is probably not on Takaro’s allowlist, so Takaro would not let it register itself by URL. Use a client id if one exists for your assistant, or ask for the host to be added.

The assistant says “Unknown operation id”

Either the assistant invented an id, or the operation is staff-only. Ask it to search first.

The call was refused because you belong to more than one domain

Tell the assistant which domain to work in; the refusal message lists them by name.

A delete was refused with a mention of a limit

That is the destructive-call brake. Confirm what should be deleted, and the assistant can continue once the window has passed.

Checking the endpoint is reachable

curl https://api.takaro.io/.well-known/oauth-protected-resource/mcp

A healthy deployment answers with a small JSON document naming the endpoint and the login server your assistant will be sent to. Anything else (a connection error, an HTML error page) means the endpoint itself is the problem, not your assistant.

Self-hosted deployments

• The endpoint is <your BASE_URL>/mcp, and the login server must be reachable over HTTPS from your users’ browsers.
• An assistant may only register itself by URL if its host is listed in keycloak.realm.mcp.permittedClientIdDomains. There is no wildcard: * matches nothing, and an empty list rejects everything. Every host in the assistant’s redirect URIs has to be listed too.
• The brake is MCP_DESTRUCTIVE_CALL_THRESHOLD (default 5) within MCP_DESTRUCTIVE_CALL_WINDOW_SECONDS (default 60).
• The response cap is MCP_MAX_RESPONSE_BYTES (default 65536).

Next steps

• The Takaro API: the same operations, called directly.
• Roles and permissions: what your assistant inherits from your account.
• The Takaro skill: the flows your assistant follows; contributions welcome.