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

Codex

1. Add the servers you need

   Run the corresponding commands:

   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.

2. Sign in

   Run this for each server you added:

   codex mcp login penumbra
   codex mcp login shapes
   codex mcp login memory
   

   Complete each browser consent flow.

3. Check the connection

   Run codex mcp list. Inside a Codex session, use /mcp to inspect the connected servers and their tools.

See Codex’s MCP documentation.

Claude Code

1. Add the servers you need

   The user scope makes the servers available in every project:

   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.

2. Sign in

   Run this for each server you added:

   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.

3. Check the connection

   Run claude mcp list. Inside Claude Code, use /mcp and confirm that each server shows as connected.

See Claude Code’s MCP documentation.

Claude.ai

1. 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.

2. Connect your account

   Select Connect beside the connector and complete the browser consent flow. Repeat for every Penumbra server you need.

3. Enable it in a conversation

   In a chat, select + → Connectors and turn on the Penumbra connectors you want Claude to use.

See Claude’s remote connector instructions.

Google Antigravity

1. 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.

2. Add the servers you need

   Antigravity requires serverUrl for remote servers:

   {
     "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.

3. 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.

See Google Antigravity’s MCP documentation.

Cursor

1. 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.

2. Add the servers you need

   Cursor uses url for Streamable HTTP servers:

   {
     "mcpServers": {
       "penumbra": {
         "url": "https://mcp.getpenumbra.ai/mcp"
       },
       "shapes": {
         "url": "https://shapes.pnbr.io/mcp"
       },
       "memory": {
         "url": "https://memory.pnbr.io/mcp"
       }
     }
   }
   
3. 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.

See Cursor’s MCP documentation.

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.

Run the first Runtime loop

Save a source and retrieve its exact wording.

Verify Shapes access

Confirm that Shapes Workbench is ready for authoring.