How to add an MCP server to Cursor, Claude Code and Codex

Connecting an MCP server is the moment your coding agent stops guessing about your database or your repos and starts reading the real thing. The catch is that Cursor, Claude Code and Codex each store MCP config in a different file with a slightly different format.

This guide shows how to add an MCP server to Cursor, Claude Code and Codex, step by step, with the same two examples in each tool: the hosted Supabase server (remote, OAuth sign-in) and GitHub's remote MCP server (remote, token in a header). New to the protocol? Start with what MCP is.

Before you add an MCP server

Three things to decide first:

• Remote or local. Remote servers are a URL (Streamable HTTP). Local servers are a command your machine runs (stdio). Both examples here are remote.
• Project or global. Project config can be committed so your team shares it. Global config follows you across projects but stays on your machine.
• Where the token lives. Never paste a token straight into a file you commit. Each tool supports environment variable references, shown below.

For Supabase, scope the server from the start with project_ref (one project only) and read_only=true (queries run as a read-only Postgres user). Supabase recommends both (Supabase MCP docs).

Add an MCP server to Cursor

Cursor reads .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project. Servers go under an mcpServers object. Remote servers take a url and optional headers, and any value can use ${env:NAME}, ${workspaceFolder} or ${userHome} interpolation (Cursor MCP docs).

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_PAT}"
      }
    }
  }
}

Things to know:

• Tool approval is on by default. Cursor asks before using MCP tools, and you can expand a call to see its arguments.
• envFile only works for local (stdio) servers. For remote servers, set the variable in your shell profile or system environment.
• Debugging: open the Output panel (Cmd+Shift+U or Ctrl+Shift+U) and pick "MCP Logs" to see connection errors, authentication issues and crashes.

Add an MCP server to Claude Code

Claude Code adds servers from the command line with claude mcp add. Each command writes to local scope (just you, this project) unless you add --scope project, which writes a .mcp.json you can commit, or --scope user for all your projects (Claude Code MCP docs).

claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Then run /mcp inside Claude Code to sign in to Supabase and check that both servers connected. claude mcp list, claude mcp get <name> and claude mcp remove <name> manage them from the shell.

If you edit .mcp.json by hand, a remote server needs "type": "http" next to its url. Use ${VAR} or ${VAR:-default} so the token stays out of the file:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

Two limits worth knowing: Claude Code warns when an MCP tool returns more than 10,000 tokens and caps output at 25,000 tokens by default, which you can change with MAX_MCP_OUTPUT_TOKENS. And claude mcp add saves config without validating credentials, so a placeholder token is accepted and fails later. Run /mcp to confirm.

Add an MCP server to Codex

Codex keeps MCP servers in ~/.codex/config.toml, or in a project's .codex/config.toml for trusted projects. The ChatGPT desktop app, the Codex CLI and the IDE extension share this config (Codex MCP docs).

From the CLI, Supabase documents this pair of commands:

codex mcp add supabase --url "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"
codex mcp login supabase

Or write the config yourself. HTTP servers take a url, and bearer_token_env_var names the environment variable that holds the token:

[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT"
default_tools_approval_mode = "writes"

Useful options from the Codex docs:

• enabled_tools and disabled_tools allow or block individual tools.
• default_tools_approval_mode accepts auto, prompt, writes or approve. writes prompts for tools that aren't marked read-only.
• startup_timeout_sec (default 10) and tool_timeout_sec (default 60) help with slow servers.
• codex mcp list shows configured servers, and /mcp in the TUI shows what's connected.

Test the connection

Ask the agent something only the server can answer:

Using the Supabase MCP tools, list the tables in my project and tell me
which ones don't have Row Level Security enabled.

If nothing happens, check the logs (Cursor's "MCP Logs", /mcp in Claude Code or Codex), confirm the environment variable is set in the shell that launched the tool, and restart the client after editing config by hand.

Keep it safe

Every connected server acts with your permissions. Claude Code's docs say to "verify you trust each server before connecting it", because servers that fetch external content can expose you to prompt injection. Keep approvals on for anything that writes, scope tokens to the minimum, and read our guide to MCP security best practices before you connect anything to production.

All three config files from this guide, ready to edit, are in our MCP config starter.

Keep reading

• What is MCP? The Model Context Protocol explained for vibe coders
• How to run coding agents safely: permissions, sandboxes and secrets
• Supabase RLS audit skill for coding agents

FAQ

Where is the MCP config file in Cursor?

Cursor reads .cursor/mcp.json in your project and ~/.cursor/mcp.json for all projects. Servers go under an mcpServers object.

How do I add an MCP server to Claude Code?

Run claude mcp add --transport http with a name and the server URL. Add --scope project to write a .mcp.json file your team can commit, then run /mcp to sign in.

Where does Codex store MCP servers?

Codex stores MCP servers in ~/.codex/config.toml, or in .codex/config.toml for trusted projects. The ChatGPT desktop app, Codex CLI and IDE extension share this config.

Why does my MCP server not connect?

Check the logs (MCP Logs in Cursor, /mcp in Claude Code or Codex), confirm the environment variable is set in the shell that launched the tool, and restart the client after editing config by hand.