> ## Documentation Index
> Fetch the complete documentation index at: https://devs.surferseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex (CLI and IDE)

> Connect Surfer to the Codex CLI or IDE extension.

export const Prompt = ({text}) => {
  const copyIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg>';
  const checkIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"></path></svg>';
  const copy = event => {
    const button = event.currentTarget;
    if (!navigator.clipboard) return;
    navigator.clipboard.writeText(text).then(() => {
      button.innerHTML = checkIcon;
      button.setAttribute('aria-label', 'Copied');
      clearTimeout(button.resetTimer);
      button.resetTimer = setTimeout(() => {
        button.innerHTML = copyIcon;
        button.setAttribute('aria-label', 'Copy prompt');
      }, 2000);
    }).catch(() => {});
  };
  return <div className="surfer-prompt not-prose">
      <div className="surfer-prompt-meta">
        <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
          <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
          <circle cx="12" cy="7" r="4" />
        </svg>
        <span>Prompt</span>
      </div>
      <div className="surfer-prompt-bubble">
        <p className="surfer-prompt-text">{text}</p>
        <button type="button" className="surfer-prompt-copy" aria-label="Copy prompt" onClick={copy}>
          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
            <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
            <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
          </svg>
        </button>
      </div>
    </div>;
};

Add Surfer from your terminal or the Codex extension's MCP settings.

## Before you start

You need your own Surfer account on a [plan that includes MCP](/mcp/credits-and-limits#plans-that-include-mcp).

<Note>
  Codex CLI, the IDE extension, and ChatGPT desktop share MCP configuration on
  the same Codex host. If Surfer is already connected there, continue to [Verify
  the connection](#verify-the-connection).
</Note>

## Connect Surfer

Choose the client you use.

<Tabs>
  <Tab title="CLI">
    <Steps>
      <Step title="Add the server">
        Register Surfer from your terminal:

        ```bash theme={"system"}
        codex mcp add surfer --url https://mcp.surferseo.com/mcp
        ```
      </Step>

      <Step title="Sign in to Surfer">
        Follow the browser sign-in prompt. If it does not open, start sign-in from your terminal:

        ```bash theme={"system"}
        codex mcp login surfer
        ```

        1. Sign in with your Surfer account in the browser window that opens.
        2. Choose the organization to connect, if you belong to more than one.
        3. Select **Authorize**, then return to your client.

        If the browser signs you in to the wrong Surfer account, follow [Disconnect or switch accounts](/mcp/authentication#disconnect-or-switch-accounts).
      </Step>
    </Steps>
  </Tab>

  <Tab title="IDE extension">
    <Steps>
      <Step title="Add the server">
        Open the Codex extension's gear menu, then select **MCP servers → Add server** and enter:

        | Setting | Value |
        | - | - |
        | Name | `surfer` |
        | Transport | **Streamable HTTP** |
        | URL | `https://mcp.surferseo.com/mcp` |

        Save the server, then select **Restart extension**.
      </Step>

      <Step title="Sign in to Surfer">
        Select **Authenticate** next to `surfer` in the MCP server list.

        1. Sign in with your Surfer account in the browser window that opens.
        2. Choose the organization to connect, if you belong to more than one.
        3. Select **Authorize**, then return to your client.

        If the browser signs you in to the wrong Surfer account, follow [Disconnect or switch accounts](/mcp/authentication#disconnect-or-switch-accounts).
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Accordion title="Configure the server in a file">
  Add this entry to `~/.codex/config.toml`, or to `.codex/config.toml` in a trusted project:

  ```toml theme={"system"}
  [mcp_servers.surfer]
  url = "https://mcp.surferseo.com/mcp"
  ```

  Start sign-in from your terminal, then complete the Surfer authorization:

  ```bash theme={"system"}
  codex mcp login surfer
  ```

  Restart your Codex session or extension to load the configuration.
</Accordion>

## Verify the connection

In the CLI, start `codex`, then run `/mcp` to see active servers. In the IDE extension, check the MCP server list, then open a new chat.

Ask your assistant:

<Prompt text="List my Surfer workspaces" />

Your assistant lists the workspaces in the organization you authorized. Each workspace has a name, type, location, and state. Choose an active workspace for content tasks.

Continue with [Skills](/mcp/skills) for guided workflows or [Use cases](/mcp/use-cases) for example requests. If the request fails, see [Troubleshooting](/mcp/troubleshooting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.