Connect MCP

Endpoints and authentication

Both servers take JSON-RPC 2.0 over HTTP POST. Always use api.gujo.ai and design.gujo.ai. Calls to gujo.ai/api/... lose the MCP headers, and tokens you get by signing in only work at the api.gujo.ai URL.

This page covers the customer MCP. The design MCP is described in Design Gallery.

Connect by signing in

Give your client just the server URL. You don't need to create a key or set an environment variable.

1. Pick your client below and press the install button, or add the command or config.
2. The first time the client calls the server, it opens your browser at the account.gujo.ai sign-in page. If you are already signed in, you go straight to the consent screen.
3. On the consent screen, check the app's name, its address, the server it connects to and the permissions it gets, then approve.
4. The client receives and keeps the token, and from then on refreshes it on its own when it expires.

The client finds where to sign in by itself, from the standard metadata the server publishes (/.well-known/oauth-protected-resource/api/mcp). It also registers itself as an app.

Permissions

Permissions on the consent screen have the same names as account API key abilities and are checked exactly the same way.

• The default permissions are mcp.read (connect over MCP) and products.read (read your library and products). They are always included when you approve.
• If the app asks for more, such as orders.read, subscriptions.read or device.install, those appear unchecked. Only the ones you check are granted.
• The tool list shows only the tools the granted permissions allow. If the app calls a tool it lacks permission for, the server answers 403 and names the missing permission, and the app can ask for consent again with it.
• Operator abilities cannot be requested.

Token lifetimes and disconnecting

• An access token lasts one hour, and the client gets a new one with its refresh token. Both tokens change on every refresh.
• A refresh token expires after 30 days without use. A connection ends 90 days after you approved it, and you sign in once more then.
• Apps you connected by signing in are listed under Connected apps in your account security settings. You can see each app's name, permissions and last use, and Disconnect revokes all of that app's tokens.
• An account can have up to 20 active connections. When it is full, disconnect the ones you no longer use.
• Tokens you get by signing in work only for MCP. Calling other account API endpoints (such as /api/products) with them returns 401.

Connect with a key (CI, scripts)

Where nobody can sign in through a browser (CI, scripts on a server, headless agents), use an account API key. Expand Connect with a key under each client below for the config.

No config contains a key. They only point at an environment variable (GUJO_API_KEY, GUJO_DESIGN_TOKEN) or the client's password prompt. Create a key with the mcp.read ability as described in Account API keys, and put the value shown once at creation into a shell environment variable.

export GUJO_API_KEY="your key"

Connect a client

{
    "mcpServers": {
        "gujo": {
            "url": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "mcpServers": {
        "gujo": {
            "url": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_API_KEY}"
            }
        }
    }
}

{
    "servers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "inputs": [
        {
            "type": "promptString",
            "id": "gujo-token",
            "password": true,
            "description": "Gujo account API key (mcp.read)"
        }
    ],
    "servers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${input:gujo-token}"
            }
        }
    }
}

claude mcp add --transport http gujo https://api.gujo.ai/api/mcp

{
    "mcpServers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "mcpServers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${GUJO_API_KEY}"
            }
        }
    }
}

codex mcp add gujo --url https://api.gujo.ai/api/mcp
codex mcp login gujo

[mcp_servers.gujo]
url = "https://api.gujo.ai/api/mcp"
bearer_token_env_var = "GUJO_API_KEY"

https://api.gujo.ai/api/mcp

URL: https://api.gujo.ai/api/mcp
Authorization: Bearer <GUJO_API_KEY>

{
    "mcpServers": {
        "gujo": {
            "serverUrl": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "mcpServers": {
        "gujo": {
            "serverUrl": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_API_KEY}"
            }
        }
    }
}

{
    "mcpServers": {
        "gujo-design": {
            "url": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_DESIGN_TOKEN}"
            }
        }
    }
}

{
    "inputs": [
        {
            "type": "promptString",
            "id": "gujo-design-token",
            "password": true,
            "description": "Gujo design agent token"
        }
    ],
    "servers": {
        "gujo-design": {
            "type": "http",
            "url": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${input:gujo-design-token}"
            }
        }
    }
}

{
    "mcpServers": {
        "gujo-design": {
            "type": "http",
            "url": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${GUJO_DESIGN_TOKEN}"
            }
        }
    }
}

[mcp_servers.gujo-design]
url = "https://design.gujo.ai/mcp"
bearer_token_env_var = "GUJO_DESIGN_TOKEN"

{
    "mcpServers": {
        "gujo-design": {
            "serverUrl": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_DESIGN_TOKEN}"
            }
        }
    }
}

Check the connection

1. Ask the agent for its tool list. The tools the granted permissions (or the key's abilities) allow appear.
2. If no sign-in window opens, check that the URL is https://api.gujo.ai/api/mcp. Start signing in again with /mcp in Claude Code or codex mcp login gujo in Codex.
3. With a key, on 401 check the key, and on 403 missing_api_key_ability check that the key has mcp.read.
4. With a key, if no tools appear, the client may not see the environment variable. Start the client again from a shell that has it.

Toolsets

Agents pick tools less accurately when they see all of them at once, so tools are grouped into toolsets. The first tools/list shows three meta tools and the tools of the library toolset.

Turning a toolset on or off makes the server send notifications/tools/list_changed. If the client sent Accept: text/event-stream, the same response comes as SSE with that notification before the result. An unknown toolset name is an unknown_toolset tool error.

One tool is one account API endpoint. Tool names, required abilities and input fields match the tool column of the API reference. Read the detail and manual of a product you bought with products_detail.

• The tool list only shows tools whose ability the key has. A key without orders.read, for example, sees no orders tools.
• Entitlement and product-scoped key checks need the arguments, so they come back at call time as tool errors such as 403 product_entitlement_required.
• The three write tools (products_setup_progress_update, device_installs_create, device_usage_create) run right away without approval.
• Endpoints that revoke the calling key or return a new key in plain text, endpoints that take file uploads, and non-JSON responses (such as bundle files) are not tools.

Sessions

1. Take the Mcp-Session-Id response header from initialize. The protocol version is 2025-11-25.
2. Send the same Mcp-Session-Id on every later request. Each session remembers its enabled toolsets.
3. Each use extends a session by 12 hours. An unknown session, or one created with another key, gets HTTP 404 with JSON-RPC -32600. Start again from initialize.

A request without the session header is treated as having only the library toolset on. Batch requests are rejected (400). Supported methods are initialize, ping, tools/list, tools/call and notifications (202 with an empty body).

Results and errors

• Success: structuredContent = {status, body}, the HTTP status and JSON body you would get calling the endpoint over REST.
• Failure: isError: true, structuredContent = {error, message, status?, body?, field?}. error is the endpoint's error code (such as product_entitlement_required), or invalid_input when an argument does not match the input fields (field names it).
• Calling a tool name you cannot see is the JSON-RPC error -32602 Unknown tool. The old mcp_tool_{id} names now get this error too.
• An unknown method is -32601.

Troubleshooting