Tokay MCP

Connect your AI agent to Tokay so they can upload code, deploy apps, recover failures, inspect usage, and keep working on the same repository later.

Last updated October 29, 2026

AI agent? Start with llms.txt.

Connect

The quickest way is Connect an assistant in Tokay. Choose the app you use, follow its steps, and the page shows when the connection lands.

Every client adds this remote Streamable HTTP endpoint.

https://mcp.tokay.io/mcp

Connecting opens a browser for OAuth approval, so there is no token to paste into the client. You choose what the assistant can do when you approve it. Every connection is listed separately in your Connections, and you can disconnect one without affecting another installation.

Any other client that signs in with a Client ID Metadata Document connects the same way.

Your ChatGPT plan and workspace settings decide whether you can add a custom MCP server. On Business, Enterprise, and Edu, an admin grants Create plugins with MCPs.

VS Code can use this workspace or user configuration.

{
  "servers": {
    "tokay": {
      "type": "http",
      "url": "https://mcp.tokay.io/mcp"
    }
  }
}

A client that cannot sign in through your browser uses an MCP token instead. Create one at Connect an assistant with a token with the grants the assistant needs. Tokay shows it once, already inside the setup for Cursor, Claude Code, Codex, and other clients. Cursor reads it from ~/.cursor/mcp.json.

{
  "mcpServers": {
    "tokay": {
      "url": "https://mcp.tokay.io/mcp",
      "headers": { "Authorization": "Bearer <your MCP token>" }
    }
  }
}

A token skips browser approval. It is listed with your assistants in Connections, marked as using a token, until it expires or you revoke it.

What your agent can do

• Import your code from GitHub, or push it with Git, and deploy it. A chat-only assistant without git can still push files.
• Return later, find the exact repository snapshot, search it, read files, make a conflict safe change, and deploy again.
• Follow Tokay's authoritative deployment readiness instead of guessing from time or logs, waiting on it rather than sleeping between checks.
• Resolve configuration, database, source, and release blockers through named tools.
• Diagnose a failed build or deployment with bounded evidence and logs.
• Report the workspace's size, its headroom, and the share used by a Project, Service, or managed database.
• Create workspaces, choose Workspace Sizes, and manage funding when the connection has that permission.
• Run a bounded read only query against a managed database.
• Use the rest of the public GraphQL surface through a read tool and a fail closed routine mutation tool.

Every tool wraps a Platform API operation, so MCP can do nothing the API cannot, and one protocol describes both. A tool earns its place by being better than the GraphQL it wraps: compact results, waits instead of polling, and errors that name the real fields. With auto-deploy on, which is the default, pushing a change is all it takes to deploy it.

MCP is for the agent you work with. Scripts and automation call the Platform API with an API token instead, because an MCP connection's OAuth needs a person. Unattended automation runs as a Bot: its own identity, a member of only the projects it needs, with only the grants it needs, whose credential outlives your tokens and whose actions are audited as the Bot. A token of your own from Connect your own script fits a script you run yourself.

Bring your code

Your agent asks whether your code is on GitHub. If it is, you link GitHub in Tokay and the agent imports the repository; fixes then arrive as pull requests. Otherwise the agent creates a Tokay repository and pushes with Git, running git init first if the folder is not a repository yet. Only an assistant without a shell or git pushes files with push_code. In Tokay's interface you do only what your agent cannot: connect it, optionally link GitHub, and optionally add a custom domain. Anything else that needs you, such as a value, an approval or a decision, your agent asks for in the conversation.

MCP is the workflow surface

MCP carries decisions, metadata, bounded source text, and structured results. It does not carry repository archives, database dumps, or service file bytes through the model context.

Large bytes use short lived capability URLs. Your agent asks Tokay for an upload or download URL, transfers the bytes over ordinary HTTP without an OAuth bearer, then continues the workflow with the handle the upload returns. This keeps a large repository faithful without turning it into thousands of tool arguments. Each upload URL takes one PUT, so a failed upload asks for a new URL. These are the same tickets the browser and the public API use.

Clients that need arbitrary GraphQL or REST calls can authorize the separate https://api.tokay.io resource and use the public API directly. Tokay MCP tokens are accepted only at https://mcp.tokay.io/mcp.

Tokay MCP and an MCP hosted on Tokay

See Deploy an MCP server when the product you are hosting is itself an MCP server.

Permissions

The first connection requests Tokay's Recommended set below. It covers everything from uploading source to recovering a failed deploy. The consent page lists every permission and lets you choose Recommended, Everything except dangerous, or your own selection, so you decide your agent's reach once.

Logs and query results can contain application data or personal information. Tokay includes PROJECT_READ_LOGS and PROJECT_QUERY because deployment and recovery are one workflow. Diagnosis returns state and explanation first and includes bounded log bodies only when requested. Queries are read only and bounded.

Member management, workspace funding, API and MCP credential creation, and permanent deletion stay outside Recommended until you choose them. Workspace creation and size or funding changes require WORKSPACE_MANAGE_BILLING. App access, meaning who can open a Service, Groups, Machines and their credentials, and public routes, is part of PROJECT_WRITE. Of these, setServiceAccess, createServicePublicRoute, and issueMachineCredential confirm first.

When your agent needs an action the connection lacks, the denial carries requiredAction with the exact PermissionActionType. On an OAuth connection, Tokay answers that tool call with HTTP 403 and an insufficient_scope challenge naming the connection's current actions plus that one. A client that supports step-up opens consent with those actions already checked, and approving replaces the connection: the old one is disconnected and the credentials it created are revoked. A manually created MCP token gets the denial in the tool result instead. Otherwise, reconnect and check it on the consent page, or create an MCP token with those grants at Connect an assistant with a token. A denial without requiredAction is about membership or a browser only step, and no new approval changes it.

Core workflow tools

Tools use the GraphQL names. A tool input that takes a Node ID is the GraphQL input field plus Id, so deployService(input: { service }) is deploy with serviceId, and a tool that reads several Node types takes id. A tool returns the GraphQL response, { data }, or { data, errors } when at least one root field resolved but some field failed, except that query_database parses each record. A field, argument, or input field guessed wrong answers with every real name in extensions.availableFields or availableArguments, and the closest in the message, except on an interface, whose message may instead name the types to select with an inline fragment. query_database and start_database_export take logicalDatabaseName, and start_database_export takes format, as their GraphQL mutations do.

Platform and byte tools

renamePlatformCredential is a routine metadata mutation. An MCP root may rename a direct leaf it can manage through mutate_platform_graphql. The mutation cannot change verifier material, grants, owner, lineage, or expiry.

Platform credential creation requires explicit CREDENTIAL_CREATE_API, CREDENTIAL_CREATE_MCP, or CREDENTIAL_CREATE_GIT. The Git action covers HTTPS and SSH. Recommended includes only the Git action, because a Git credential reaches only repositories the connection already reaches. A credential created for the same Person or Bot is narrower and cannot create another credential. API and MCP leaves default to one hour, cannot exceed 24 hours, and cannot outlive a finite root. Git HTTPS and SSH leaves have optional expiry and no 24 hour cap. An omitted expiry resolves to the root expiry when it is finite. registerSshKey accepts only a public key and returns no secret. Provisioning an independent Bot credential requires authority to manage the Bot, and its confirmation states that the new credential survives this connection. A Machine credential opens your deployed app and cannot manage Tokay, so issueMachineCredential needs PROJECT_WRITE, not a creation grant.

Rotation preserves the authority of the presented MCP root that was not created through OAuth and atomically revokes that root plus its direct leaves. The replacement token appears once. A lost committed response is not retryable or recoverable. Roots created through OAuth must disconnect and complete OAuth again.

previewPlatformCredentialRevocation shows the Self or Lineage scope and every affected credential, plus one review set of independent credentials created across the lineage boundary. Revoking one requires explicit selection and current authority. A selected API or MCP root brings its direct leaves.

Confirmations and retry safety

Dangerous actions confirm in the Platform API itself, the same for MCP, the API, and the browser. These are the actions that destroy or replace data (deletes, purges, database imports, rollbacks past a database change older code may not handle, and gated releases), spend money (creating a workspace, or changing or ending its funding), create, rotate, or revoke a credential (including Machine credentials, disconnecting an OAuth app or GitHub, and regenerating a FUNCTION URL), change a Service's access with setServiceAccess in either direction or add a public route, loosen release safety, or stop a value someone set from reaching a Service without naming a new one (ignoreServiceEnvVarNeed, clearServiceEnvVarOverride). Adding or removing an audience member or Group member does not confirm. The first call changes nothing and returns CONFIRMATION_REQUIRED with the impact and a ten minute token in errors[].extensions.confirmation. Repeating the unchanged call with confirmationToken added to its input executes it. A changed request, changed target state, different credential, or expired token returns a fresh confirmation instead.

An agent explicitly granted the action may evaluate the impact and make the second call itself, as with funding under WORKSPACE_MANAGE_BILLING. Show the impact to the user first when the action destroys data or widens access. Funding does not grant workspace membership. Owners may attach their own account, while a current payer may end only their own funding even after losing membership.

Repository writes use caller stable idempotency keys, so retrying a lost response returns the same commit instead of a duplicate. Reusing the key for different input fails. Root rotation is the deliberate exception: the predecessor dies at commit and a lost successor response has no recovery path.

Unknown readiness actions and blocker types stop safely.

Privacy and retention

• Tokay validates the connection's live root credential for every MCP request.
• Disconnecting the connection blocks the next tool call and any unused capability URL. A source operation Tokay already accepted continues under its durable repository state; disconnect is not cancellation.
• Secret values are accepted only by write only tools and are never returned.
• Tokay does not log OAuth bearers, source contents, database query text or results, application log bodies, release commands, capability tokens, or credentials shown once.
• Operational logs may record the tool name, principal and target IDs, support reference, result size, status, and duration.
• Platform OAuth connections stay active until disconnected or revoked. Capability URLs expire quickly. Most work once, while a database export or service file download URL works for an hour and resumes, and a database import upload URL resumes for a day. Confirmation tokens expire after ten minutes and stop working once their action runs.

Read the privacy policy and security model. Email hello@tokay.io for support.

Troubleshooting