Connect Penumbra to your agent

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
Claude Code
Claude.ai
Google Antigravity
Cursor

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.

Run this for each server you added:

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

Complete each browser consent flow.

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.

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.

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.

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.

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.

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.

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.

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.

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"
    }
  }
}

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.

Get started

Mental model

Connect Penumbra to your agent

Choose your servers

Add the servers

Verify Runtime

If the connection fails

Run the first Runtime loop

Verify Shapes access

​Choose your servers

​Add the servers

​Verify Runtime

​If the connection fails

Run the first Runtime loop

Verify Shapes access

Choose your servers

Add the servers

Verify Runtime

If the connection fails