MCP Server — Claude Code Configuration

This chapter covers configuring Claude Code to use the WakaStart MCP server hosted on this documentation site.

---

.mcp.json configuration

Create a .mcp.json file at the root of your WakaApp project:

jsonCopy
{
  "mcpServers": {
    "wakastart-docs": {
      "url": "http://localhost/api/mcp",
      "transport": "http"
    }
  }
}

To point to staging or production:

jsonCopy
{
  "mcpServers": {
    "wakastart-docs": {
      "url": "https://docs.wakastart.app/api/mcp",
      "transport": "http"
    }
  }
}

URLs per environment:

---

Questions you can ask Claude

Once configured, query directly from Claude Code:

Via list_endpoints

• "Show me all authentication endpoints"
• "Which endpoints accept POST?"
• "List all invitation endpoints with their required rights"

Via get_endpoint_spec

• "What body is expected for POST /api/invitations?"
• "What error codes can DELETE /api/invitations/:id return?"
• "Generate a curl example for POST /api/auth/enrich"

Via search_docs

• "How does PKCE work in Wakastart?"
• "What is an AppRight?"
• "How do I configure rate limiting on the Wakapp side?"

Via get_auth_flow

• "Explain the Wakastart auth flow for a frontend app"
• "How does M2M auth work with an API key?"

Via get_error_code

• "Why am I getting a 401?"
• "What is BOLA?"
• "When does the API return a 409?"

---

Verifying the server

Test that the server responds:

bashCopy
# Handshake
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0"}}}'

# List available tools
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_endpoints","arguments":{"tag":"Auth"}}}'

---

Example Claude Code session

Once .mcp.json is configured:

textCopy
You: "Generate the TypeScript code to call POST /api/invitations"

Claude: [Calls list_endpoints with tag="Invitations"]
        [Calls get_endpoint_spec with path="/api/invitations", method="POST"]
        → Generates the code with the correct types, required headers, and error handling

---

Using resources/read

To read a full documentation chapter in Claude:

bashCopy
curl -X POST https://docs.wakastart.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "resources/list",
    "params": {}
  }'

Then read a resource:

bashCopy
curl -X POST https://docs.wakastart.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "resources/read",
    "params": { "uri": "wakastart://openapi/v1" }
  }'

---

Best practices

• Use list_endpoints + get_endpoint_spec at the start of a sprint.
• The MCP is read-only — no risk of modifying the platform.
• In CI/CD, do not include .mcp.json in the production container — local documentation use only.
• If the docs instance is down, the static OpenAPI spec remains accessible via public/openapi.json.

Go further

• MCP Overview: tools, resources, technical characteristics
• Endpoint reference: static table of all routes