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.

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 does not read, write, or edit source code on your own computer.

If you instead want a local AI agent (such as Claude Code or Cursor) to pull a project down and build, check, or preview its code on your own machine, that is a separate local (stdio) Caffeine MCP server, distributed through the Caffeine CLI. It is an early developer preview and is not covered by this guide.

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
Start a Caffeine AI chat session for a project, watch it live, read the transcript, send replies, and submit clarification forms
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

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 — the first time your AI tool calls a Caffeine tool, it opens your browser to sign in at caffeine.ai.

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 will list the available Caffeine tools once the server responds.
Start a new chat. Add the Caffeine connector from the connector menu in the composer.
The first time you ask the assistant to use a Caffeine tool, ChatGPT will open your browser to sign in. Complete the sign-in at caffeine.ai 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)

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. The Caffeine tools become available to the agent the first time you ask for them, and Cursor will open your browser to sign in.

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 to the Caffeine sign-in page; complete sign-in 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. The first time the tool calls a Caffeine action, it opens your default browser to a Caffeine sign-in page. Complete sign-in there and return to the tool. 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, per browser session. 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. If caffeine_auth_status says you are not signed in, ask the tool to use a Caffeine action — that will trigger the browser sign-in.

Projects

Tool	Description
`caffeine_list_projects`	List all your projects
`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_delete_project`	Permanently delete a project

Chat sessions

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`	Send a freeform reply to a clarification question
`caffeine_chat_submit_form`	Submit a structured clarification form
`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 raw feed events for a session
`caffeine_chat_detach_session`	Mark a local session as detached
`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-only tools — building, the local build preview (running your project on your own machine), importing, exporting, cloning, and CLI configuration — are intentionally not exposed through the hosted MCP server. They require code on your own machine, and so live in the local Caffeine CLI instead. (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.)

Troubleshooting

The connector saves but no Caffeine tools appear

Some AI tools cache the connector's tool list. Fully close and reopen the tool. If the tools still do not appear, open a new chat and ask the assistant to call caffeine_auth_status directly — that often forces the tool to re-fetch the server's tool list.

The OAuth flow is triggered when your AI tool first calls a protected Caffeine tool. If you only saved the connector and never asked the assistant to do anything, no sign-in will happen. Send a prompt like:

Use the Caffeine connector. List my projects.

That tells the tool to call a protected action, and it should open your browser to sign in.

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?

The MCP server itself is free to connect from any Caffeine account. Individual actions follow the same plan rules as the Caffeine app — for example, creating projects on plans with a project limit, using features that require a paid tier, or running tools that depend on a feature your plan does not include. If a tool fails because of a plan restriction, the assistant will surface the same message you would see in the Caffeine app.

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, and URLs. Your project's source code is not sent to your AI tool through this connector. If you ask the assistant to do something that would require the source code, 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. Signing out of an AI tool's connector revokes that tool's session 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 signs that specific AI tool out of Caffeine.

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

Yes — a separate local (stdio) Caffeine MCP server, distributed through the Caffeine CLI. Use it when you want a local AI agent (such as Claude Code or Cursor) to work with a project's code on your own machine: cloning it down and running builds, checks, and previews locally. That is what exposes the local-only tools the hosted server deliberately omits. 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 locally.

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.