Setting Up the Caffeine MCP Server – Caffeine AI

Connect ChatGPT, Claude, Perplexity, or any other MCP-compatible AI tool directly to your Caffeine account. Once it is set up, you can ask the assistant you already use every day to list your projects, start a Caffeine chat session, watch a build progress live, and continue a conversation that's running on Caffeine — all from inside the AI tool, without copy-pasting between tabs. AI tools that can run commands on your machine, such as Claude Code or Cursor, can go one step further and work on a project's code locally with the Caffeine CLI.

To let an assistant use your published app and its data, rather than build and manage your projects, see Using Your App from Claude and Other AI Assistants.

The Caffeine MCP server is a hosted endpoint that exposes Caffeine actions as tools your AI assistant can call on your behalf. It speaks the open Model Context Protocol (MCP) standard, so any MCP-compatible client can connect to it with one piece of configuration: the server URL.

Alpha: The Caffeine MCP server is currently in alpha. The endpoint and the verified clients below work today, but the tool surface and behaviour may still change and you may occasionally hit rough edges. If something looks like an integration bug rather than a configuration issue, let Caffeine support know.

What the Caffeine MCP server is

MCP is an open standard for letting AI assistants safely call external tools. The Caffeine MCP server is the Caffeine implementation of that standard, hosted by Caffeine and accessible to any AI tool that supports remote MCP connectors.

What it does — and what it doesn't. This connector lets your AI assistant drive the Caffeine AI — Caffeine's own cloud agent that builds and edits your app. Your assistant sends prompts to the Caffeine AI, starts and watches build sessions, and reads back transcripts and project details on your behalf. Everything runs on Caffeine's infrastructure: the connector itself does not read, write, or edit source code on your own computer.

There is one bridge to local work. If your AI tool can run shell commands on your machine (a desktop agent such as Claude Code, Cursor, or the Codex CLI), the connector can hand it a step-by-step guide — via the caffeine_local_setup tool — for working on a project's code locally with the Caffeine CLI: installing the CLI, downloading the project's source, editing it, validating it, and uploading the result back to Caffeine as a new draft. The connector supplies the instructions and, when the CLI signs in, approves that sign-in under your account. Every command runs on your machine, through the CLI, with your consent. See Working on your code locally below.

Once your AI tool is connected, the assistant gains a Caffeine toolset and can:

Check whether you are signed in to Caffeine
List your projects and look up details for any one of them
Create new projects and delete existing ones
Publish a project's draft to its live URL
Start a Caffeine AI chat session for a project, watch it live, read the transcript, and answer the Caffeine AI's questions
Resume an existing session or discover sessions that are still active
Get the browser chat URL for any project, so you can switch over to the Caffeine web UI whenever you want
Switch between your personal account and the team workspaces you belong to
See where your credits went, by charge type and project
Fetch the local development guide and approve the Caffeine CLI's sign-in, so an AI tool that can run shell commands can download a project's code and work on it directly with the CLI

You sign in once per AI tool through your browser. The server keeps your session, so the tool you set up today still works tomorrow.

Before you start

You need:

A Caffeine account that you can sign in to at caffeine.ai.
One of the supported AI tools below.

You do not need to install anything on your machine. The Caffeine MCP server runs on Caffeine's infrastructure — your AI tool talks to it directly over HTTPS.

Supported AI tools

The Caffeine MCP server works with any client that supports remote MCP connectors over Streamable HTTP. The clients listed below have been verified:

ChatGPT (Developer Mode connectors)
Claude (Desktop and web custom connectors)
Claude Code (CLI)
Cursor
VS Code with GitHub Copilot (1.99 or later)
OpenAI Codex (CLI and desktop)
Perplexity (Custom Remote Connectors)

If your client supports remote MCP servers over Streamable HTTP, it will work with the same URL even if it is not in this list.

Connection details

You need only one piece of information for every client:

Server URL: https://mcp.caffeine.ai/mcp
Transport: Streamable HTTP
Authentication: OAuth (browser-based, owned by your AI tool)

Each client below shows where to enter this URL. The OAuth flow is identical for everyone — when your AI tool connects, it opens your browser to sign in to Caffeine. See Signing in below for the steps.

Connecting your AI tool

Pick the section that matches your tool. The setup is equivalent across clients — only the place you put the URL changes.

ChatGPT

ChatGPT can connect to the Caffeine MCP server through its connectors system. You need Developer Mode enabled.

In ChatGPT, open Settings.
Go to Connectors.
Click Create (or Add custom connector).
For the MCP Server URL, enter:
```
https://mcp.caffeine.ai/mcp
```
Set the transport to Streamable HTTP and the authentication to OAuth.
Save the connector. ChatGPT asks you to sign in, following the steps in Signing in below, and then lists the available Caffeine tools.
Start a new chat. Add the Caffeine connector from the connector menu in the composer.
If ChatGPT didn't ask you to sign in when you saved the connector, it opens your browser the first time you use it. Complete the steps in Signing in below and return to ChatGPT.

If ChatGPT does not show the connector creation option, your account does not have Developer Mode enabled — see the Troubleshooting section.

Claude (Desktop and claude.ai)

Caffeine is listed in Claude's connector directory, so you can connect it from there without entering the URL. You can also add it yourself as a custom connector, as described below.

Claude supports custom connectors that point at a remote MCP server URL.

Option A — Through the Claude UI. In Claude, open Settings → Connectors (the exact path varies slightly between Desktop and web). Add a custom connector with:

Name: Caffeine
Type: HTTP / Streamable HTTP
URL: https://mcp.caffeine.ai/mcp

Save the connector. The first time you use it in a chat, Claude opens your browser for sign-in.

Option B — Through the config file. For Claude Desktop on macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json (on Windows, %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "caffeine": {
      "type": "http",
      "url": "https://mcp.caffeine.ai/mcp"
    }
  }
}

If the file already exists, merge the caffeine entry into the existing mcpServers object. Then fully restart Claude Desktop.

Claude Code

Claude Code is the Claude CLI. Add the Caffeine MCP server with one command:

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

--scope user registers it for every project. Leave that out and run the command from a project directory to register it only there.

Or commit a project-level .mcp.json to git:

{
  "mcpServers": {
    "caffeine": {
      "type": "http",
      "url": "https://mcp.caffeine.ai/mcp"
    }
  }
}

Inside Claude Code, type /mcp to confirm the server is listed and to step through the OAuth flow on first use.

Cursor

Edit ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project root (just this project):

{
  "mcpServers": {
    "caffeine": {
      "type": "http",
      "url": "https://mcp.caffeine.ai/mcp"
    }
  }
}

Restart Cursor. On first use, Cursor opens your browser to sign in, and the Caffeine tools become available to the agent after that.

VS Code with GitHub Copilot

Requires VS Code 1.99 or later and an active GitHub Copilot subscription.

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "caffeine": {
      "type": "http",
      "url": "https://mcp.caffeine.ai/mcp"
    }
  }
}

Restart VS Code. To verify, open the command palette and run MCP: List Servers — you should see caffeine listed. On first use, VS Code opens your browser to complete the sign-in.

OpenAI Codex

For the Codex CLI:

codex mcp add caffeine --url https://mcp.caffeine.ai/mcp

Or edit ~/.codex/config.toml:

[mcp_servers.caffeine]
url = "https://mcp.caffeine.ai/mcp"

Verify with:

codex mcp list

The Codex desktop app reads the same configuration. Restart it after changing the config.

Perplexity

Perplexity supports remote MCP through Custom Remote Connectors.

Open Account settings → Connectors.
Click Add Custom Remote Connector.
Fill in:
- MCP Server URL: https://mcp.caffeine.ai/mcp
- Transport: Streamable HTTP
- Authentication: OAuth
Save the connector.
Open the connector card and click Authenticate. Your browser opens the Authorize Caffeine MCP page. Follow the steps in Signing in below and return to Perplexity.
The Caffeine connector is now available for new conversations.

Organisation-wide Perplexity connectors need an admin to enable and share them from Enterprise settings.

Signing in

The Caffeine MCP server uses OAuth. Your AI tool — not the server, and not Caffeine support — owns the sign-in flow. When your AI tool connects to the server, it opens your default browser to sign in:

On the Authorize Caffeine MCP page, click Open Caffeine authorization. Caffeine opens in a new tab.
Sign in to Caffeine if asked.
On the Approve Sign-in page, check that the account shown is the one you want to connect, and click Approve.
Go back to your AI tool. In a desktop browser, the first tab finishes connecting by itself. On a phone or tablet, tap Continue.

From then on, your tool is connected.

You can confirm sign-in at any time by asking:

Use the Caffeine connector. Check my Caffeine authentication status.

The assistant will call caffeine_auth_status and report back with your account details.

Sign-in is held per AI tool connection and lasts up to 90 days, or 30 days if you don't use the connector. If you sign in with ChatGPT today, that does not automatically sign in your Claude or Perplexity connector — each tool has its own session.

Verifying it works

A good first end-to-end test is:

Open a new conversation in your AI tool.
Ask:

Use the Caffeine connector. List my Caffeine projects.
If you have not signed in yet, the tool opens the browser sign-in. Complete it.
The assistant calls caffeine_list_projects and returns your projects with their IDs and URLs.

If you see your projects, the integration is working. Next, ask:

Use the Caffeine connector. Show me details for project <PROJECT_ID> and give me its chat URL.

That exercises both caffeine_show_project and caffeine_chat_url, and confirms the connector can answer follow-up questions about a specific project.

What you can do with the connector

Once the connector is set up, your assistant has access to the following Caffeine tools. You do not need to memorise tool names — describe what you want in plain language and the assistant will pick the right one.

Authentication

Tool	Description
`caffeine_auth_status`	Check whether your AI tool is signed in to Caffeine

Sign-in itself is handled by your AI tool, not by a tool call. Your tool can't reach any Caffeine tool until you sign in.

Projects

Tool	Description
`caffeine_list_projects`	List the projects in the selected workspace
`caffeine_show_project`	Get details for one project
`caffeine_show_project_preview`	Show a visual preview card for a project (for ChatGPT Apps and other MCP-UI hosts that can render it)
`caffeine_create_project`	Create a new project
`caffeine_go_live`	Publish the draft you previewed to the project's live URL (its custom domain, if one is connected)
`caffeine_delete_project`	Permanently delete a project

Before publishing, the assistant checks which draft you previewed. If a newer draft was built since, it asks which one you want to publish.

Workspaces and credits

Tool	Description
`caffeine_list_workspaces`	List your personal account and the team workspaces you can switch to
`caffeine_workspace_status`	Show which workspace the project and chat tools are using
`caffeine_use_workspace`	Switch to a team workspace, or back to your personal account
`caffeine_credit_usage`	Show where your credits went, by charge type and project, per day or week. In a team workspace, only admins can see usage.

Chat sessions

When the Caffeine AI needs a decision from you, for example "Ready to start?", the assistant asks you and sends your answer with caffeine_chat_reply. If nobody answers within five minutes, the Caffeine AI decides on its own and carries on.

Tool	Description
`caffeine_chat_start_session`	Start a Caffeine AI chat session for a project
`caffeine_chat_send`	Send a prompt to a project's chat
`caffeine_chat_reply`	Answer a question from the Caffeine AI
`caffeine_chat_active_sessions`	Discover likely active chat sessions across your projects
`caffeine_chat_resume_session`	Reattach to a session and wait for the next stable state
`caffeine_chat_watch_session`	Stream live updates from a session
`caffeine_chat_session_status`	Summarise an active session
`caffeine_chat_session_transcript`	Show the transcript of a session
`caffeine_chat_session_feed`	Collect progress events for a session
`caffeine_chat_detach_session`	Stop following a session (an acknowledgement only; the session keeps running)
`caffeine_chat_list`	List chat messages for a project
`caffeine_chat_tail`	Poll messages until the AI reaches a stable state
`caffeine_chat_url`	Get the browser URL for a project's chat

Local development

Tool	Description
`caffeine_local_setup`	Return the step-by-step guide for working on a project's code locally with the Caffeine CLI, and approve the CLI's sign-in

caffeine_local_setup returns the instructions. During the guide's sign-in step, the assistant calls it again with the code the CLI prints, which approves the CLI's sign-in under your Caffeine account without a browser. It is meant for AI tools that can execute shell commands on your machine; the Working on your code locally section below explains the workflow it describes.

Local actions — building, uploading a local build as a draft preview, importing, exporting, cloning, and CLI configuration — are intentionally not executed through the hosted MCP server. They require code on your own machine, and so live in the local Caffeine CLI instead; caffeine_local_setup is the hosted server's pointer to that workflow. (This is distinct from caffeine_show_project_preview above, which only returns a read-only preview card for a project and is available on the hosted server.)

Working on your code locally

If your AI tool runs on your own machine and can execute shell commands — Claude Code, Cursor, the Codex CLI, and similar desktop agents — you have a second way to change a project beyond chatting with the Caffeine AI: let the assistant edit the code directly on your machine.

Ask for it in plain language:

Use the Caffeine connector. I want to work on project <PROJECT_ID>'s code locally.

The assistant calls caffeine_local_setup, which returns the workflow it should follow:

Ask for your consent. The workflow installs a global npm package, signs the CLI in to your Caffeine account, downloads project code to your disk, and later uploads your changes as a new draft — the assistant should confirm each of these with you before starting.
Install the Caffeine CLI from npm (npm install -g @caffeineai/cli, or via npx if a global install is undesirable).
Authenticate the CLI. The assistant runs caffeine auth device start, approves the code it prints through the connector, and then runs caffeine auth device complete. You don't need a browser. If approval through the connector fails, the assistant opens the sign-in link in your browser instead. The CLI keeps its own login on your machine, separate from the connector's.
Download the project with caffeine projects clone.
Edit the code locally, following Caffeine's app, Motoko, and component skills.
Validate with caffeine check --fix.
Upload the result with caffeine preview --build, which builds the project, uploads it to Caffeine as a new draft, and returns a preview URL.

Your project's code never travels through the MCP connector in this workflow — the CLI talks to Caffeine directly, exactly as it would if you ran the commands yourself.

Hosted AI tools that cannot run commands on your machine — ChatGPT, Claude on the web, Perplexity — skip this entirely and use the chat tools instead: describe the change you want, and the Caffeine AI modifies, builds, and deploys the code on Caffeine's infrastructure. The connector tells assistants to fall back to the chat tools whenever local commands are unavailable or a local step fails, so you do not need to pick the right path yourself.

Troubleshooting

The connector saves but no Caffeine tools appear

Your AI tool only gets the tool list after you sign in, and some tools cache it. Fully close and reopen the tool. If the tools still do not appear, check that the connector shows as connected or authenticated in your AI tool. If it doesn't, start the sign-in from the connector's settings, or remove the connector and add it again.

Your AI tool must sign in before it can use the connector at all. Some tools start the sign-in only when you first use the connector. If you only saved the connector, send a prompt like:

Use the Caffeine connector. List my projects.

If no browser opens, remove the connector and add it again.

Some clients hold OAuth state per chat session. Start a fresh chat and try again. If the problem persists, remove the connector and add it back — that resets the local connector cache without affecting your Caffeine account.

"Server unreachable" or "connector failed to connect"

Confirm that you can reach caffeine.ai from your browser. The Caffeine MCP server is hosted on the same infrastructure, so if Caffeine itself is reachable but https://mcp.caffeine.ai/mcp is not, the most likely cause is a corporate firewall or VPN that blocks the mcp.caffeine.ai host.

ChatGPT doesn't show a "Create connector" option

Developer Mode for connectors must be enabled on your ChatGPT account. Most consumer ChatGPT plans need Developer Mode turned on in your account settings before custom connectors appear. If you have a managed ChatGPT account (Team, Enterprise, Education), an admin may need to enable connectors at the workspace level.

Perplexity custom connectors are not visible in my account

Custom Remote Connectors are a Perplexity feature that is rolled out per plan and per region. If your Perplexity account does not show Add Custom Remote Connector, your plan does not currently include the feature. Check Perplexity's connector documentation for the latest availability.

Frequently asked questions

Do I need a paid Caffeine plan to use the MCP server?

No. The MCP server is free to connect from any Caffeine account. Individual actions follow the same rules as the Caffeine app — for example, the project limit, and spending credits to build or go live. If a tool fails because of one of these limits, the assistant tells you why, for example that the project limit is reached.

Does the connector send my source code to my AI tool?

No. The Caffeine MCP server only returns the data the tools you call ask for — typically project metadata, chat messages, transcripts, URLs, and the local setup guide. Your project's source code is not sent to your AI tool through this connector. In the local workflow, the code reaches your machine through the Caffeine CLI's own connection to Caffeine — not through the connector — and only after you agree to clone it. If you ask the assistant to do something that would require the source code and it cannot work locally, it can hand off to the Caffeine web chat by calling caffeine_chat_url.

Your sign-in is held by the Caffeine MCP server on Caffeine's infrastructure, scoped to the AI tool you signed in from. The AI tool only holds an opaque token — it does not hold your Caffeine credentials directly. Removing an AI tool's connector deletes that tool's sign-in without affecting your other tools.

Can I connect more than one AI tool at the same time?

Yes. Add the connector to each tool independently. Each tool has its own session, so signing in or out of one does not affect the others.

How do I remove the connector?

In ChatGPT, Claude, Perplexity, Cursor, and VS Code, remove the connector from the same UI you added it in. In Claude Code, run claude mcp remove caffeine. In OpenAI Codex, run codex mcp remove caffeine. Removing the connector deletes that AI tool's sign-in, and your other tools stay signed in. Signing out of Caffeine everywhere ends every connector's sign-in.

Is there a local version that runs on my own machine?

For most local-code work you no longer need one. If your AI tool can run shell commands, the hosted connector's caffeine_local_setup tool hands it the full workflow for cloning, editing, checking, and uploading a project with the Caffeine CLI — see Working on your code locally above.

Separately, the Caffeine CLI also ships a local (stdio) Caffeine MCP server that exposes the local actions (build, check, preview, clone, import/export) as MCP tools directly. It is an early developer preview — even less mature than the hosted server described here — and is not yet documented in this knowledge base.

The hosted endpoint on this page is the right choice for ChatGPT, Claude, Perplexity, and any tool that cannot reach a process running on your laptop — and whenever you want to drive the Caffeine AI rather than edit code yourself.

Is the hosted MCP server in alpha?

Yes. The Caffeine MCP server is currently in alpha. The endpoint URL and the tool surface work for the clients listed above, but they are still evolving — clients and tools are added regularly, and details may change between releases. If you hit something that looks like an integration bug rather than a configuration issue, contact Caffeine support with the name of the AI tool you are using and the exact error message you saw.