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

# Connect Penumbra to your agent

> Add the Penumbra MCP servers to Codex, Claude Code, Claude.ai, Google Antigravity, or Cursor.

Connect the servers you need, complete browser sign-in, and check that your
agent can see their tools. These clients can use Penumbra's OAuth flow, so you
do not need to put an API key in their configuration.

## Choose your servers

| Server name | Use it to...                | Streamable HTTP URL              |
| ----------- | --------------------------- | -------------------------------- |
| `penumbra`  | Work with project knowledge | `https://mcp.getpenumbra.ai/mcp` |
| `shapes`    | Design and evolve Shapes    | `https://shapes.pnbr.io/mcp`     |
| `memory`    | Remember across sessions    | `https://memory.pnbr.io/mcp`     |

Runtime (`penumbra`) is the usual starting point. Add Shapes when the agent
needs to create or change the project's semantic contract. Add Memory when
context should persist across sessions.

## Add the servers

<Tabs>
  <Tab title="Codex">
    <Steps>
      <Step title="Add the servers you need">
        Run the corresponding commands:

        ```bash theme={null}
        codex mcp add penumbra --url https://mcp.getpenumbra.ai/mcp
        codex mcp add shapes --url https://shapes.pnbr.io/mcp
        codex mcp add memory --url https://memory.pnbr.io/mcp
        ```

        Codex CLI and the Codex IDE extension share this configuration.
      </Step>

      <Step title="Sign in">
        Run this for each server you added:

        ```bash theme={null}
        codex mcp login penumbra
        codex mcp login shapes
        codex mcp login memory
        ```

        Complete each browser consent flow.
      </Step>

      <Step title="Check the connection">
        Run `codex mcp list`. Inside a Codex session, use `/mcp` to inspect
        the connected servers and their tools.
      </Step>
    </Steps>

    See [Codex's MCP documentation](https://developers.openai.com/codex/mcp).
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the servers you need">
        The `user` scope makes the servers available in every project:

        ```bash theme={null}
        claude mcp add --transport http --scope user penumbra https://mcp.getpenumbra.ai/mcp
        claude mcp add --transport http --scope user shapes https://shapes.pnbr.io/mcp
        claude mcp add --transport http --scope user memory https://memory.pnbr.io/mcp
        ```

        To limit a server to the current project, use `--scope local` instead.
      </Step>

      <Step title="Sign in">
        Run this for each server you added:

        ```bash theme={null}
        claude mcp login penumbra
        claude mcp login shapes
        claude mcp login memory
        ```

        Complete each browser consent flow. You can also start sign-in from the
        `/mcp` panel inside Claude Code.
      </Step>

      <Step title="Check the connection">
        Run `claude mcp list`. Inside Claude Code, use `/mcp` and confirm
        that each server shows as connected.
      </Step>
    </Steps>

    See [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp).
  </Tab>

  <Tab title="Claude.ai">
    <Steps>
      <Step title="Add a custom connector">
        Open **Customize → Connectors**, select **+**, then choose
        **Add custom connector**. Paste one Penumbra URL from the table above
        and select **Add**.

        Free Claude accounts can add one custom connector; add Runtime first.
        On Team and Enterprise plans, an Owner first adds each server from
        **Organization settings → Connectors → Add → Custom → Web**. Members
        then find it under **Customize → Connectors**.
      </Step>

      <Step title="Connect your account">
        Select **Connect** beside the connector and complete the browser consent
        flow. Repeat for every Penumbra server you need.
      </Step>

      <Step title="Enable it in a conversation">
        In a chat, select **+ → Connectors** and turn on the Penumbra connectors
        you want Claude to use.
      </Step>
    </Steps>

    See [Claude's remote connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
  </Tab>

  <Tab title="Google Antigravity">
    <Steps>
      <Step title="Open the MCP configuration">
        In the agent side panel, select **… → MCP Servers → Manage MCP
        Servers → View raw config**.

        Antigravity stores the global file at
        `~/.gemini/config/mcp_config.json`. A workspace-only configuration
        can live at `.agents/mcp_config.json`.
      </Step>

      <Step title="Add the servers you need">
        Antigravity requires `serverUrl` for remote servers:

        ```json theme={null}
        {
          "mcpServers": {
            "penumbra": {
              "serverUrl": "https://mcp.getpenumbra.ai/mcp"
            },
            "shapes": {
              "serverUrl": "https://shapes.pnbr.io/mcp"
            },
            "memory": {
              "serverUrl": "https://memory.pnbr.io/mcp"
            }
          }
        }
        ```

        Save the file. No `oauth` block is required because the Penumbra
        servers support dynamic client registration.
      </Step>

      <Step title="Sign in">
        Open **Agent Settings** with **Cmd+,** on macOS or **Ctrl+,** on
        Windows and Linux. Under **Customizations**, select **Authenticate**
        beside each server. Complete the browser flow, copy the authorization
        code, paste it into Antigravity, and select **Submit**.
      </Step>
    </Steps>

    See [Google Antigravity's MCP documentation](https://antigravity.google/docs/mcp).
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open the MCP configuration">
        Use `~/.cursor/mcp.json` to make the servers available everywhere, or
        `.cursor/mcp.json` in a project to limit them to that workspace.
      </Step>

      <Step title="Add the servers you need">
        Cursor uses `url` for Streamable HTTP servers:

        ```json theme={null}
        {
          "mcpServers": {
            "penumbra": {
              "url": "https://mcp.getpenumbra.ai/mcp"
            },
            "shapes": {
              "url": "https://shapes.pnbr.io/mcp"
            },
            "memory": {
              "url": "https://memory.pnbr.io/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Connect and check the tools">
        Open **Customize** in Cursor, enable each Penumbra server, and complete
        the OAuth browser flow when prompted. Confirm that the server's tools
        appear under **Available Tools**.
      </Step>
    </Steps>

    See [Cursor's MCP documentation](https://cursor.com/docs/mcp).
  </Tab>
</Tabs>

## Verify Runtime

Ask the agent:

> Use the Penumbra Runtime MCP to identify the active project, the Shapes
> available to it, and the kinds of knowledge it can work with. Do not make
> changes.

A successful response names the actual project and concrete entity types. If
the answer is generic, tell the agent to use the connected `penumbra` MCP
rather than answer from prior knowledge.

## If the connection fails

* **The client says the server is unauthorized:** reopen its MCP or connector
  settings and start OAuth again.
* **The server does not appear:** confirm that the URL ends in `/mcp`, then
  reload the client or its MCP configuration.
* **The wrong server was added:** Runtime uses `mcp.getpenumbra.ai`, Shapes
  uses `shapes.pnbr.io`, and Memory uses `memory.pnbr.io`.
* **A managed workspace blocks custom MCPs:** ask the workspace administrator
  to allow or add the Penumbra server.

<Columns cols={2}>
  <Card title="Run the first Runtime loop" icon="play" href="/getting-started/quickstart">
    Save a source and retrieve its exact wording.
  </Card>

  <Card title="Verify Shapes access" icon="shapes" href="/shapes/connect">
    Confirm that Shapes Workbench is ready for authoring.
  </Card>
</Columns>