Connect the hosted MCP

The hosted Codelab MCP is a Streamable HTTP server at:

https://mcp.codelab.app/mcp

It authenticates with Clerk OAuth (the same account as app.codelab.app) and writes prod Neon. A hosted write is visible on the production builder and published sites without a sync.

Do not put an Authorization header or API key in the config. On first connect the client gets a 401, reads OAuth metadata from /.well-known/oauth-protected-resource/mcp, and opens Clerk. There is no static bearer.

Hosted vs local#

Which database a call hits is which host you connected to — not a flag on the tool.

This repository’s .mcp.json stays on the local URL so HMR and reload_server keep writing to the sandbox. Public clients add the hosted URL. Do not retarget this repo at the hosted host to “write prod directly.”

Claude Code / Claude Desktop#

Project .mcp.json (type must be http; a url with no type is skipped):

{
  "mcpServers": {
    "codelab": {
      "type": "http",
      "url": "https://mcp.codelab.app/mcp"
    }
  }
}

Or:

claude mcp add --transport http codelab https://mcp.codelab.app/mcp

Complete the Clerk OAuth prompt on first connect.

Cursor#

.cursor/mcp.json (project) or ~/.cursor/mcp.json (user):

{
  "mcpServers": {
    "codelab": {
      "url": "https://mcp.codelab.app/mcp"
    }
  }
}

In Settings → Tools & MCP, connect the server and finish Clerk OAuth. No headers block.

Grok#

Prefer the native url transport. Do not wrap the endpoint in npx mcp-remote.

grok mcp add --transport http codelab https://mcp.codelab.app/mcp

Or in ~/.grok/config.toml:

[mcp_servers.codelab]
url = "https://mcp.codelab.app/mcp"

Grok handles OAuth. In a session, open /mcps and press i to authenticate. Tokens land in ~/.grok/mcp_credentials.json.

Codex#

Same shape this repo uses in .codex/config.toml — url only, no bearer env var. User config is ~/.codex/config.toml:

[mcp_servers.codelab]
url = "https://mcp.codelab.app/mcp"

Or:

codex mcp add codelab --url https://mcp.codelab.app/mcp

Then codex mcp login codelab for Clerk OAuth.

After connect#

The MCP keeps a conversation-scoped active app. Tools that need it (list_pages, add_element, …) fail without it.

1. list_apps — discover appIds. If the list is empty, create_app first.
2. set_context with { "appId": "..." } — omit contextId on the first call; keep the one it returns.
3. get_context with that contextId — verify the session.

Pass contextId to every later app-scoped tool. After that, the canvas is the source of truth: inspect with load_page_outline / find_element_in_page, then add_element and update_props. See the introduction, the model (App, Page, Element, Component), behavior (Action, Function, Types), and Registry / Props for the tree those tools edit.