diff --git a/model-context-protocol/developer-portal.mdx b/model-context-protocol/developer-portal.mdx index 962f6f2..4ad2e8c 100644 --- a/model-context-protocol/developer-portal.mdx +++ b/model-context-protocol/developer-portal.mdx @@ -26,9 +26,19 @@ https://developer.world.org/api/mcp Developer portal API keys start with `api_`. +## Authentication errors + +Every method, including `initialize`, requires the API key. Authentication failures return HTTP 200 with JSON-RPC error code `-32001`, not an HTTP 401. The message distinguishes missing or malformed credentials from a key that was parsed but rejected: + +```json +{"jsonrpc": "2.0", "id": 1, "error": {"code": -32001, "message": "API key is required."}} +``` + +For a parsed but rejected key, the message is `API key is not valid.` Check that the client sends `Authorization: Bearer ` and copies the complete key from secure storage. Keys are shown only once; if yours is lost, generate a new key and update every client using the old one. The endpoint only accepts `POST`; `GET` returns HTTP 405 with `allow: POST, OPTIONS`. + ## Connect your client -Replace `api_...` with the API key you copied from the Developer Portal. +Replace `api_...` with the API key you copied from the Developer Portal. Codex and Cursor read the key from the `WORLD_DEVELOPER_API_KEY` environment variable at startup, so set it persistently (for example, in your shell profile, loaded from a secrets manager) rather than with a one-off `export`. VS Code prompts for the key once and stores it securely. @@ -36,17 +46,15 @@ Replace `api_...` with the API key you copied from the Developer Portal. claude mcp add world-developer-portal \ https://developer.world.org/api/mcp \ --transport http \ - --scope project \ + --scope local \ --header "Authorization: Bearer api_..." ``` ```bash codex mcp add world-developer-portal \ - --env WORLD_DEVELOPER_API_KEY=api_... \ - -- npx -y mcp-remote https://developer.world.org/api/mcp \ - --transport http-only \ - --header 'Authorization:Bearer ${WORLD_DEVELOPER_API_KEY}' + --url https://developer.world.org/api/mcp \ + --bearer-token-env-var WORLD_DEVELOPER_API_KEY ``` @@ -58,7 +66,7 @@ Replace `api_...` with the API key you copied from the Developer Portal. "world-developer-portal": { "url": "https://developer.world.org/api/mcp", "headers": { - "Authorization": "Bearer api_..." + "Authorization": "Bearer ${env:WORLD_DEVELOPER_API_KEY}" } } } @@ -70,12 +78,20 @@ Replace `api_...` with the API key you copied from the Developer Portal. ```json { + "inputs": [ + { + "type": "promptString", + "id": "world-developer-api-key", + "description": "World Developer Portal API key", + "password": true + } + ], "servers": { "world-developer-portal": { "type": "http", "url": "https://developer.world.org/api/mcp", "headers": { - "Authorization": "Bearer api_..." + "Authorization": "Bearer ${input:world-developer-api-key}" } } } @@ -139,9 +155,18 @@ upload_app_image { app_id, image_type: "content_card", image_base64 | source_url upload_app_image { app_id, image_type: "showcase_1", image_base64 | source_url } ``` +## Timeouts and retries + +A timeout or dropped connection doesn't tell you whether a call went through, and these tools don't replay the original result. Re-read state (`get_world_id_signing_key`, `get_world_id_registration_status`, `get_app_config`) before you retry: + +- `configure_world_id` and `rotate_world_id_signing_key`: the private key is only in the original response. If that response is lost, the key is unrecoverable, but the portal still applies its signer address. Retrying `configure_world_id` returns the existing registration with `signing_key: null`. Retrying `rotate_world_id_signing_key` fails with `-32004` (`rotation_in_progress`) until the registration status is `registered` again. If `get_world_id_signing_key` shows a signer address you don't hold, wait until `get_world_id_registration_status` reports `registered`, then rotate again from a trusted channel (see [Security notes](#security-notes)). +- `submit_app_for_review`: if the first call went through, a retry fails with `-32004` `Only unverified apps can be submitted.` Check `get_app_config` for the review status instead. + ## Security notes - Store generated World ID private keys immediately. They are returned once and are not recoverable from the portal. +- `configure_world_id` and `rotate_world_id_signing_key` return the private key as a tool call result, not a one-time dialog — it passes through the assistant's model context and, depending on the client, may be persisted in session transcripts or debug logs. Treat it as sensitive. If it was generated through a client whose logs aren't under your team's control, don't just rotate again from that same client — the replacement key would leak through the identical path. Rotate from the Developer Portal dashboard instead: it generates the new key in your browser and sends only the signer address. +- Keep API keys out of files you commit. Claude Code's `--scope project` writes the header to `.mcp.json`, which is meant to be committed; the examples above use local scope, an environment variable, or an input prompt instead. - Use a separate API key per local agent or project when possible. - Delete or rotate API keys that are no longer needed. - Confirm destructive actions before asking the assistant to rotate a signer key or submit an app for review. diff --git a/model-context-protocol/index.mdx b/model-context-protocol/index.mdx index 887360e..1fb6b75 100644 --- a/model-context-protocol/index.mdx +++ b/model-context-protocol/index.mdx @@ -36,7 +36,7 @@ World provides two MCP servers: ## Client support -Both MCP servers use streamable HTTP. Most modern MCP clients can connect directly to an HTTP MCP server. Clients that only support stdio can connect through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). +Both MCP servers use streamable HTTP. Most modern MCP clients, including Codex CLI (`codex mcp add --url `), can connect directly to an HTTP MCP server. Clients that only support stdio can connect through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Keep developer portal API keys scoped to trusted local MCP clients. The Developer Portal MCP can mutate apps in your team. diff --git a/model-context-protocol/world-docs.mdx b/model-context-protocol/world-docs.mdx index d3c4817..902aa74 100644 --- a/model-context-protocol/world-docs.mdx +++ b/model-context-protocol/world-docs.mdx @@ -28,7 +28,7 @@ The docs MCP does not require authentication. ```bash - codex mcp add world-docs -- npx -y mcp-remote https://docs.world.org/mcp --transport http-only + codex mcp add world-docs --url https://docs.world.org/mcp ``` @@ -65,6 +65,8 @@ The docs MCP does not require authentication. | Tool | Purpose | | --- | --- | | `search_world_documentation` | Search and retrieve relevant World documentation for the current task. | +| `query_docs_filesystem_world_documentation` | Run shell-like queries (`rg`, `grep`, `find`, `tree`, `ls`, `cat`, `head`, `tail`, `stat`, `wc`, `sort`, `uniq`, `cut`, `sed`, `awk`, `jq`) over the full docs corpus, including OpenAPI specs, to read a full page or spec instead of a search snippet. | +| `submit_feedback` | Submit feedback about the documentation to the World docs team. | ## Suggested prompts @@ -78,4 +80,4 @@ Search the World docs for World ID verification and explain which endpoint this ## When to use it -Use the docs MCP for read-only documentation lookup. To create or configure apps in the developer portal, use the [Developer Portal MCP](/model-context-protocol/developer-portal). +Use the docs MCP for documentation lookup and filesystem-style queries over the docs corpus (read-only except for `submit_feedback`). To create or configure apps in the developer portal, use the [Developer Portal MCP](/model-context-protocol/developer-portal).