tokyo.how API & MCP server documentation

When to use tokyo.how

• Find a practical guide for a Tokyo trip, such as transport, payments, or everyday etiquette.
• Research the steps involved in moving to or living in Tokyo.
• Retrieve a relevant article and cite its URL in an assistant's answer.

These are published guides. Check linked official sources for changing prices, eligibility, and opening times. Use official live services for current disruptions and emergencies.

Connect with MCP

Set your MCP client's server URL to https://tokyo.how/mcp and choose Streamable HTTP. The endpoint is stateless and does not issue a session ID. You do not need to register, create an API key, or obtain an OAuth token.

Initialize the client, then send the initialized notification. The examples use protocol version 2025-11-25; use the version returned by initialization in subsequent MCP-Protocol-Version headers.

curl -sS https://tokyo.how/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"tokyo-how-example","version":"1.0.0"}}}'

Discover the current tools and their input schemas:

curl -sS https://tokyo.how/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -sS https://tokyo.how/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Search for guides using a supported language, en or ja:

curl -sS https://tokyo.how/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_guides","arguments":{"query":"suica card","lang":"en","limit":5}}}'

Use the returned slug with get_guide to retrieve the full article. The website has additional language editions, but MCP tool inputs currently accept English and Japanese.

The separate request_article tool and POST /api/article-request create an editorial submission and can notify the operator. Use them only when the user asks to submit a request or report. A successful response acknowledges receipt and does not guarantee publication, a reply, or notification delivery.

Request Markdown

Use Accept: text/markdown on an HTML page. A successful conversion returns Content-Type: text/markdown and Vary: Accept. Browser requests continue to receive HTML. Missing pages keep their HTTP 404 status when returned as Markdown.

curl -sS -L -i \
  -H 'Accept: text/markdown' \
  https://tokyo.how/

curl -sS -L -i \
  -H 'Accept: text/html' \
  https://tokyo.how/

Start with the content index when you need to find a suitable article before requesting its body.

Use the CLI

The tokyo.how CLI is a downloadable script for Node.js 22 or later. Save it locally and review the file before running it. It provides read-only access to the public guides.

curl -fSLo tokyo-how.mjs https://tokyo.how/cli/tokyo-how.mjs
# Review the downloaded file in your editor before running it.
node tokyo-how.mjs --help
node tokyo-how.mjs search "suica card" --lang en --limit 5 --json
node tokyo-how.mjs get suica-card --lang ja
node tokyo-how.mjs categories --lang en
node tokyo-how.mjs list --lang en
node tokyo-how.mjs latest --lang ja --limit 5

Commands are search, get, categories, list, and latest. Use --lang en or --lang ja, --limit where supported, and --json for machine-readable output. Run --help for command details. No package-manager installation is required.

Use tools in a supported browser

On browsers that support WebMCP, tokyo.how registers search_tokyo_guides and get_tokyo_guide when the page loads. Both read public guide content in English or Japanese. They do not submit article requests or access saved conversations.

WebMCP is an evolving browser API and is not available in every browser. The regular website, MCP endpoint, and CLI remain usable without it.

Discovery documents

API catalog

RFC 9727 links to the APIs, their descriptions, and liveness status.

OpenAPI

HTTP operations, request bodies, and response schemas.

AI catalog

MCP metadata, the OpenAPI document, and agent instructions.

MCP metadata

Endpoint, tool names, supported languages, and access information.

Agent skill

When to use the service, how to search, and how to cite a guide.

Content index

An entry point to published guide content.

Access model

Public access and editorial submission behavior.

A2A Agent Card

Live read-only A2A 1.0 guide finder.

OAuth issuer

Optional anonymous client enrollment and device consent.

Protected resource

The optional token-protected guide API.

Poppy discovery

Website-only Poppy 0.1 discovery; no Poppy sessions or account access.

Liveness

Application response status; does not test every tool or external dependency.

Application liveness confirms that the application can respond. It does not exercise every MCP tool, search asset, or external email service.

Use the A2A guide finder

Discover the A2A Agent Card and send A2A 1.0 JSON-RPC requests to /api/a2a with A2A-Version: 1.0. The guide finder uses the official A2A SDK. It returns a synchronous Message with published search results or article text; it does not run background tasks, retain conversations, fetch submitted URLs, or submit editorial requests.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "example-message-1",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "suica card"
        }
      ]
    }
  }
}

To retrieve an article, use a data part such as {"data":{"slug":"suica-card","lang":"en"}}. Search data accepts query, lang (en or ja), and limit (1–10). The results include canonical source URLs. Each message is independent. Files, URL inputs, streaming, and task history are not supported.

Optional registered agent access

Public MCP and A2A work without registration. For a separate client identity, the agent registration guide describes anonymous client provisioning and OAuth device consent. The user approves a short code at the verification page, then the agent exchanges its device code for a guides:read Bearer token for GET /api/agent/guides. Tokens expire within one hour and can be revoked immediately.

This does not create a personal account or verify a person's identity. It grants only access to public guides and cannot authorize editorial submissions. Client credentials expire in 24 hours. Secrets are stored as hashes in private storage with an additional one-day cleanup policy. Codes expire in ten minutes and are consumed atomically to prevent concurrent replay.

The Poppy manifest declares website-only access under protocol version 0.1. Poppy sessions, account sign-in, and Poppy conversations are not advertised. OAuth device consent is the separate registered-guide service described above.

API errors, rate limits, and versioning

API transport errors return JSON with a stable error code and a recovery hint. Unknown /api/ paths return HTTP 404 as application/problem+json. MCP keeps JSON-RPC error envelopes, including protocol and tool errors. Use POST /mcp; GET receives HTTP 405 with an Allow header.

Registration has a best effort limit of 10 requests per 60 seconds per client IP per Worker isolate. Other public API, MCP, and A2A requests share a limit of 120 requests per 60 seconds. Counters reset when the isolate restarts and are not a global quota. Responses include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds), and RateLimit-Policy. HTTP 429 also includes Retry-After in seconds. Preflight requests do not consume quota. Infrastructure protection may apply additional limits.

The HTTP API contract is version 1, described in OpenAPI. Additive fields may appear without a major version change; clients should ignore unknown fields. Breaking HTTP changes will use a new major URL path and keep the previous interface available for at least 90 days after announcement here. Deprecation will be announced here with a migration guide and a sunset date, and affected HTTP responses will carry Deprecation and Sunset headers. No interface is currently deprecated. A2A uses protocol version 1.0. MCP protocol versioning is negotiated separately during initialization.

Citations and support

Link to the article you used and credit tokyo.how. Access to a public API does not grant additional content-reuse rights; follow the terms of service and privacy policy.

For integration questions or errors, use the contact page. The MCP client guide has additional connection instructions.