Chattee MCP server documentation

Chattee MCP server is a remote Model Context Protocol server that lets AI assistants such as Claude Code, Claude.ai, Cursor, Codex and ChatGPT create, change, deploy and publish full web apps on Chattee. This page shows how to connect each client, how authentication and scopes work, what the 35 tools do, and the limits you will run into.

What is the Chattee MCP server?

The Chattee MCP server lets the AI assistant you already use build complete web apps on Chattee: it creates a project from your brief, relays the plan for your approval, follows the build, and publishes the app to a Live URL. It is one remote endpoint, signed in with OAuth or a personal access token.

It speaks the Model Context Protocol (revisions 2025-11-25 and 2026-07-28) over Streamable HTTP, at one URL:

https://chattee.ai/mcp/connect

Through it your assistant can create a project from a brief, relay the plan Chattee proposes and your answer to it, watch the build, hand you the Draft preview, publish to a Live URL, start projects from templates or export them as templates, read and write files, manage environment variables and managed resources, read the database, and check your credits. Chattee builds full web apps: a React front end, a Node back end, a managed Postgres database, authentication, file storage and email, deployed and hosted on chattee.ai.

The one rule that shapes everything: plans and money decisions stay with you. A plan is shown to you in full and only you approve it; a run that reaches its budget pauses, and its allowance goes up only to a total you name. Credits are bought in the builder, never by your assistant.

What can I ask my assistant to do with Chattee?

Ask in your own words, the way you would brief a developer: your assistant turns the request into Chattee tool calls and shows you what comes back. A new app goes through a plan you approve; a small change can go straight in. The table shows real requests and the tools they used.

The first three rows are real runs from Chattee's MCP benchmark: the request as the simulated user typed it (translated where the run was in German), and the tools the assistant called, in the order it first called them. The others are single requests.

Requirements

You need three things: a Chattee account, an MCP client that speaks Streamable HTTP, and a way to sign in. Hosted clients sign in with OAuth and need nothing else; header-based clients use a personal access token. Your account API key is refused on purpose, because it is neither scoped nor revocable.

• A Chattee account (start free). The free plan includes credits.
• An MCP client: Claude Code, Claude.ai or Claude Desktop, Cursor, Codex CLI, ChatGPT, or your own agent on the Claude Agent SDK.
• Either a personal access token (created on the AI assistants page in the builder) or a client that signs in with OAuth. Your account API key does not work here.

How do I add the Chattee MCP server to Claude Code?

Claude Code adds the Chattee MCP server with one command and signs in with OAuth, so no token is pasted anywhere. Add it for your user, so it is there in every project; a team that shares a repository can commit an .mcp.json instead, with each person's own token read from an environment variable.

Add the server once, then sign in:

claude mcp add --transport http chattee --scope user https://chattee.ai/mcp/connect

--scope user adds Chattee for your user, so it is there in every project rather than only in the current folder (Claude Code's default scope). Sign in from your shell:

claude mcp login chattee

Inside Claude Code, /mcp does the same: choose Chattee there. Either way Claude Code opens Chattee's consent page, you approve, and the tools appear as mcp__chattee__<tool>. To use a personal access token instead of OAuth, pass it as a header:

claude mcp add --transport http chattee --scope user https://chattee.ai/mcp/connect --header "Authorization: Bearer chattee_pat_…"

For a project-scoped setup that a team can share, put this in .mcp.json at the repository root. The file holds no token: Claude Code replaces ${CHATTEE_PAT} with the CHATTEE_PAT environment variable, so everyone on the team uses their own personal access token and the file can be committed as it is:

{
  "mcpServers": {
    "chattee": {
      "type": "http",
      "url": "https://chattee.ai/mcp/connect",
      "headers": {
        "Authorization": "Bearer ${CHATTEE_PAT}"
      }
    }
  }
}

Set the variable before you start Claude Code, for example in your shell profile (~/.zshrc or ~/.bashrc): export CHATTEE_PAT=chattee_pat_…. Never write the token itself into .mcp.json, and never commit it anywhere.

Then ask Claude Code, for example: "Build a booking page for my yoga studio on Chattee and show me the plan before you approve it."

How do I add Chattee as a custom connector in Claude.ai and Claude Desktop?

Claude.ai, Claude Desktop and the Claude mobile apps connect to Chattee as a custom connector: you paste the server URL once, sign in to Chattee, and approve the permissions. The connection uses OAuth 2.1, works on every Claude plan, and then shows up in every chat where you turn the connector on.

Custom connectors are available on every plan (the Free plan allows one custom connector):

1. Open Customize → Connectors (Team and Enterprise owners: Organization settings → Connectors, then Add → Custom → Web).
2. Click +, choose Add custom connector, paste https://chattee.ai/mcp/connect as the URL and click Add.
3. Connect it: Claude opens Chattee's consent page. Sign in, review the permissions and approve.

Chattee then shows up as a connector you can enable per chat, on the web, in Claude Desktop and in the mobile apps. No token is pasted into Claude.

How do I add the Chattee MCP server to Cursor?

Cursor installs the Chattee MCP server with one click, or from a few lines in mcp.json, and then signs in with OAuth on Chattee's consent page. Because Cursor ignores configured headers once a server offers OAuth, signing in is the only way to authenticate here; a personal access token in the file does nothing.

Add to Cursor

Or add the server to ~/.cursor/mcp.json (or the project's .cursor/mcp.json) yourself:

{
  "mcpServers": {
    "chattee": {
      "url": "https://chattee.ai/mcp/connect"
    }
  }
}

Cursor detects that the server offers OAuth and asks you to sign in; approve on Chattee's consent page.

How do I add the Chattee MCP server to Codex CLI?

Codex CLI connects to Chattee with a personal access token that it reads from an environment variable, so the token never sits in a config file. Add the server with one command or three lines of TOML, and keep the default wait: Codex ends any tool call after 60 seconds.

Put a personal access token in the CHATTEE_PAT environment variable, then add the server:

codex mcp add chattee --url https://chattee.ai/mcp/connect --bearer-token-env-var CHATTEE_PAT

Or write the same into ~/.codex/config.toml:

[mcp_servers.chattee]
url = "https://chattee.ai/mcp/connect"
bearer_token_env_var = "CHATTEE_PAT"

Codex ends a tool call after 60 seconds, so keep wait_for_run's default of 45 seconds; the tool returns before that and Codex simply calls it again.

How do I connect the Chattee MCP server to ChatGPT?

ChatGPT connects MCP servers in Developer mode, on the page it now calls Plugins (it used to say connectors), on OpenAI's paid plans and on the web. Chattee connects through OAuth only: you paste the server URL, approve on Chattee's consent page, and then pick Chattee in a conversation.

OpenAI offers Developer mode on its paid plans (Plus, Pro, Business, Enterprise and Edu) and on the web only; in a Business, Enterprise or Edu workspace an admin may have to allow it first:

1. Open Settings → Security and login and turn on Developer mode.
2. Go to ChatGPT Plugins, click +, enter a name (Chattee) and a short description, and paste https://chattee.ai/mcp/connect as the server URL of the connection. Create it.
3. ChatGPT sends you to Chattee's consent page; sign in and approve.
4. In a new conversation, choose Developer mode from the + menu and select Chattee.

Personal access tokens are not accepted by ChatGPT, which is fine: the OAuth flow grants the same scopes, and you revoke the connection in Chattee on the AI assistants page.

How do I use the Chattee MCP server from the Claude Agent SDK?

An agent you build with the Claude Agent SDK reaches Chattee through the same remote server: pass it in the query() options with a personal access token read from the environment. The server enforces scopes, but not your approval policy, so your agent decides when a plan may be approved; keep a human in that loop.

Pass the server in the query() options, with a personal access token as the bearer, read from the CHATTEE_PAT environment variable so the token never sits in your code:

mcpServers: {
  chattee: {
    type: "http",
    url: "https://chattee.ai/mcp/connect",
    headers: { Authorization: "Bearer " + process.env.CHATTEE_PAT },
  },
}

Allow the tools with allowedTools: ["mcp__chattee"], and keep a human in the loop for approve_plan — the server refuses nothing here, so your agent's own policy is what keeps a plan from being approved unseen.

The Chattee skill and tools.json

The Chattee skill teaches an agent how to work with Chattee: the build loop, the approval rule, what each outcome means and every tool. It is one Markdown file, plus a zip for Claude.ai. tools.json lists the same tools as data. A plugin, once it is listed, installs the connection and the skill together.

• Agent skill: skill.md teaches an agent the build loop, the approval rule and every tool, for any client that reads Agent Skills (Claude Code, Cursor, Codex, the Claude Agent SDK). Claude.ai takes the same skill as chattee-skill.zip: upload it under Customize → Skills.
• Tools as JSON: tools.json lists every tool with its group, scope, access and inputs, for agents and directories that want data rather than prose.

Authentication: OAuth or personal access tokens

There are two ways to sign in and one set of scopes. Hosted clients use OAuth 2.1 and send you to Chattee's consent page; header-based clients send a personal access token. Either way the scopes you grant decide which tools work, and you revoke a connection or a token on the AI assistants page.

• OAuth 2.1 is what hosted clients use (Claude.ai, ChatGPT, Cursor, Claude Code's /mcp sign-in). The client identifies itself with a client ID metadata document or dynamic registration, proves possession with PKCE (S256), and sends you to Chattee's consent page. The page shows the client's name with its verified domain, or marks a client that registered itself as unverified and shows where approving sends you back to. Access tokens live 1 hour and refresh tokens 30 days; a refresh rotates the token, and a reused one revokes the whole grant.
• Personal access tokens (chattee_pat_…) are for header-based clients: Claude Code with --header, Codex, the Agent SDK, scripts. Create them on the AI assistants page, with the scopes you want and an optional expiry. The token is shown once and stored hashed. Revoke it on the same page.

Least privilege: a token with only projects:read and usage:read can look at everything and change nothing; add projects:write to build, and publish only if your assistant should put changes live.

A tool called without its scope answers with an insufficient_scope result that names the scope and where to grant it; nothing is changed. Connected apps and tokens are listed, and revoked, on the AI assistants page.

MCP tools reference

The Chattee MCP server has 35 tools in eight groups, listed below with the scope each one needs and what it may do to your data. Every result is Markdown for the assistant plus structured data, and every link it returns (builder chat, Draft preview, Live URL) is absolute, so your assistant can hand it to you.

Account and workspaces

Who you build as: your workspaces, and the credits a build draws on.

Projects

A project is one web app, with its own Draft preview and Live URL.

¹ With attachments, create_project, send_message and refine_plan also need projects:read.

Chats

Each chat is one conversation with the agent; a project runs one thing at a time.

Build runs

Start a run, wait for its decision points, and relay your decisions on the plan and on the agent's questions.

¹ With attachments, create_project, send_message and refine_plan also need projects:read.

² wait_for_run only posts the answer you give when your client shows the agent's question as a form.

³ stop_run ends the run in progress, or one paused at its credit limit; work already done stays on the Draft.

Publishing

Move the Draft to Live, follow the release, or roll back to an earlier one.

Templates

Start a project from a template, or turn a deployed project into one.

Files

Read the code, or make a small, certain change; for anything larger, send an edit so the agent builds and verifies it.

Configuration and data

The app's settings, its managed resources and read-only database queries.

⁴ With env: live, set_env_vars also needs publish.

The build loop and human approval

Every build follows the same loop: a planning run, your approval, the build, and a publish when you ask for it. Your assistant drives it with a handful of tools and waits in between, because a build takes 5–90 minutes. Two decisions never leave you: approving a plan, and spending more than a run's budget.

1. create_project (or send_message into an existing chat with mode: plan) starts a planning run.
2. wait_for_run returns when the plan is ready. Your assistant shows you the full plan and the builder link.
3. You say yes — approve_plan — or give feedback — refine_plan. Approval deploys the containers and starts the implementation.
4. wait_for_run, repeatedly, until the run completes. A run takes 5–90 minutes; each wait returns after at most 240 seconds with progress so far, and a timed_out_waiting outcome just means "call it again".
5. If the agent asks something (awaiting_input), your assistant relays the question and your answer goes back through answer_question. Clients that support MCP elicitation get the question as a form instead.
6. When the run completes, the closing summary and the Draft preview link come back. publish_project when you ask for it; the Live URL comes back the same way.

Budget pauses, an expired card or missing credits end a wait with an escalate outcome and links to the builder. A paused run's budget goes up only to a total you name: your assistant passes your number on with continue_run, and saves it as your default only if you say so separately. A run paused at its limit ends by itself after 30 minutes if nobody decides, and stop_run ends it at once; its work is kept, and your next message continues it as a new run with a fresh credit limit. Credits are bought in the builder; nothing on this endpoint buys them.

Limits and rate limits

Each limit below is enforced by the server and named in its answer when you hit it, so your assistant can wait or narrow the call instead of guessing. Waits are capped so no client drops a call, calls are rate-limited per user, and long reads come back in windows you page through.

• wait_for_run waits 45 seconds by default; get_release_status waits 0 seconds by default, so it answers at once unless you pass wait_seconds. Both wait at most 240 seconds per call. Longer is not useful: Claude Code drops an HTTP tool call after five minutes without progress.
• 120 calls per minute per user, across all your tokens and connected apps; beyond that a rate_limited result with retry_after_seconds. A wait in flight keeps the run going.
• 20 concurrent waits per user, one run per project at a time, and your plan's project limit.
• Attachments: up to 10 per message, text up to 256 KB and binary files up to 5 MB each, and at most 20 MB in total per message.
• read_file returns at most 200,000 characters per call. A longer window comes back with truncated: true and next_offset_line, and the result says how to read on with offset_line and limit_lines.
• get_chat shortens long messages (truncated: true) and returns older messages through before: pass the result's next_before to read the page before this one.
• get_run_logs caps every answer and says when it cut one; narrow it with tail or source.
• Idempotency keys on mutating tools are remembered for 24 hours; a service restart forgets them.

Security

The endpoint is the only public surface of the Chattee MCP server; token checks and every call into Chattee run behind it on the same host. Tokens are stored hashed, scopes are checked on every call, content passes the builder's guardrails, and every tool call lands in an audit log.

• The endpoint is the only public surface. Token verification and every call to Chattee's control plane run on loopback inside the same host.
• Tokens are stored hashed. OAuth uses PKCE S256, exact redirect URIs (loopback ports excepted, per RFC 8252), single-use codes and rotating refresh tokens; the consent page shows a client's verified domain and marks a self-registered client as unverified, so an impersonating client is visible.
• Scopes are enforced on every call; the endpoint refuses the account API key.
• Content passes the same guardrails as the builder. A guardrails block revokes every token and connected app of the account.
• Every tool call is written to an audit log kept for 30 days. In the builder chat, a message your assistant sent is marked with the client that sent it, for example "via Claude Code".
• Revoke a token or a connected app any time on the AI assistants page.

Troubleshooting

Most errors name their own fix: the result carries a code, a sentence on what happened and often a link into the builder. Below are the codes you are most likely to meet, each with what to do about it. If a call fails without a code, report it with the time of the call.

• 401 invalid_token — the token was revoked, has expired, or is the account API key. Create a personal access token, or reconnect so the client signs in again.
• token_inactive — the credential stopped working during the call: it was revoked, or it expired. A connected app signs in again on its next request (reconnect it if it does not); a personal access token cannot recover, so create a new one on the AI assistants page and use it instead.
• email_unconfirmed — the email address of your Chattee account is not confirmed yet. Confirm it with the link in the email Chattee sent you (the builder can send it again), then try again.
• account_blocked — your Chattee account is suspended, and nothing on this endpoint works until it is reinstated. Contact us.
• internal_error — something failed inside Chattee. Try the call once more; if it fails again, report it with the time of the call.
• insufficient_scope — the result names the missing scope. Grant it on the token, or reconnect the app and accept the permission.
• rate_limited — wait the retry_after_seconds; nothing was lost and the run continues.
• conflict_busy — another chat of the project holds the workspace; the result names it. Wait there, or stop that run.
• attachment_invalid — an attachment's base64 is not valid base64. Encode the file again, or send a text file as text.
• too_many_tasks — your account has too many long-running tasks open on the server (clients that use MCP tasks). Let some finish or cancel them, then try again; the runs themselves are not affected.
• Cursor keeps asking to sign in — Cursor ignores Authorization headers when a server offers OAuth. Remove the header and sign in.
• Codex reports a timeout — Codex ends tool calls at 60 seconds. Keep the default wait; do not pass timeout_seconds above 50.
• 503 introspection_unavailable — Chattee could not verify tokens for a moment. Retry after a few seconds; the client keeps its token.

Changelog

• 2026-10-15 — The docs and the landing page are written in Spanish, French and Portuguese too, besides English and German: /es/docs/mcp, /fr/docs/mcp and /pt/docs/mcp, each with its Markdown twin. The agent skill and tools.json stay English.
• 2026-10-02 — A run paused at its credit limit ends by itself after 30 minutes if nobody decides, and stop_run ends it at once (outcome ended); get_credits reports the limit a run starts with and the most it may be raised to; create_project takes the first run's limit and approve_plan the build's own allowance, each only as a number you name.
• 2026-10-01 — The tools are a table per group, with each tool's scope and what it may do to your data; example prompts from real runs; the Chattee skill (skill.md, and a zip for Claude.ai) and tools.json; an assistant raises a paused run's budget only to a total you name. Claude Code: the setup command adds Chattee for your user (--scope user), and claude mcp login chattee signs in from the shell. The Claude.ai and ChatGPT steps follow both apps' current menus.
• 2026-09-26 — First release: 35 tools, OAuth 2.1 with PKCE and personal access tokens, both protocol revisions, MCP elicitation and tasks for clients that declare them, a closing summary at the end of every build.

FAQ

What can the Chattee MCP server do?

It lets your AI assistant build a complete web app on Chattee from a brief: create the project, relay the plan for your approval, follow the build, hand you the Draft preview and publish to a Live URL. It can also read and change files, manage environment variables and managed resources, query the database read-only and start from templates.

How do I get started with the Chattee MCP server?

Create a free Chattee account, add https://chattee.ai/mcp/connect to your assistant (one command in Claude Code, a custom connector in Claude.ai, a JSON entry in Cursor), sign in with OAuth or a personal access token, and ask your assistant to build something. The setup for each client is on this page.

Which AI assistants work with the Chattee MCP server?

Claude Code, Claude.ai, Claude Desktop and the Claude mobile apps, Cursor, Codex CLI, ChatGPT in Developer mode, and agents built on the Claude Agent SDK. Any other MCP client that speaks Streamable HTTP works too; mcp-remote bridges a client that only speaks stdio.

Is the Chattee MCP server free?

Connecting is free. Building spends the credits of your Chattee plan, exactly as building in the browser does, and the free plan includes credits to start with. A run that reaches its budget pauses; its allowance goes up only to a total you name, and credits are bought in the builder.

Does Chattee deploy and host the app?

Yes. Every project gets a Draft preview, and publishing puts it on a Live URL on chattee.ai or your own domain, with a managed Postgres database, sign-in, file storage and email when the app needs them. Your assistant never handles servers, containers or deploy scripts.

Can my assistant approve a plan on its own?

No. Every plan is shown to you and approved by you, in your chat or in the builder. The tool descriptions forbid self-approval, and a token can be limited to read-only scopes if you want to be sure.

Can my assistant raise a run's budget?

Only to a total you name. A run that reaches its budget pauses, and your assistant hands you the builder link. If you tell it a new total yourself, it continues the run with exactly that allowance, and keeps it as your default only after a separate yes. If nobody decides, the paused run ends by itself after 30 minutes and keeps its work; your next message continues it as a new run. Your assistant never buys credits: plans and credits are bought in the builder.

How is this different from letting a coding agent build the app itself?

A coding agent on its own writes code on your machine, and hosting, the database, sign-in, email and deploys are yours to assemble. Through Chattee your assistant hands the brief to a builder that plans, builds, deploys and hosts the whole app, while you approve the plan and decide when it goes live.

Which MCP protocol versions are supported?

Both current revisions: 2025-11-25, the sessionful one every shipping client speaks today, and 2026-07-28, the stateless one with tasks and input-required results. The transport is Streamable HTTP. There is no stdio package; mcp-remote bridges a client that needs one.

Can I use my account API key instead of a token?

No. The endpoint refuses the account key on purpose: a personal access token is scoped and revocable, the account key is neither. Create a token on the AI assistants page, or let the client sign in with OAuth.

How long does a build take?

A full app takes 5–90 minutes; a small edit a few. wait_for_run returns at every decision point and otherwise after at most 240 seconds, so your assistant keeps polling until the run needs you.

What happens if my assistant disconnects during a build?

Nothing, on the Chattee side: runs live in the backend, not in the connection. Reconnect and call wait_for_run again, or open the chat in the builder, where the same run continues.

Is this documentation available in other languages?

Yes: in German at /de/docs/mcp, Spanish at /es/docs/mcp, French at /fr/docs/mcp and Portuguese at /pt/docs/mcp, and the landing page under the same prefixes (/de/mcp and so on). The agent skill and tools.json are English only, because agents read them.