MCP for AI clients

HarperHarbor exposes a Model Context Protocol server backed by the same services as Open API v1. An AI client uses OAuth to act on behalf of the signed-in user. Tools cover card authoring, usage queries and lane status, subject to the user’s permissions.

ノート

Confirm the MCP endpoint and available tools with the platform team during onboarding. The examples below show the connection settings.

Connect

The server speaks streamable HTTP and uses OAuth 2.1 with dynamic client registration, so most clients need only the URL.

Claude Code

claude mcp add --transport http harperharbor https://api.harperharbor.com/mcp

The first tool call opens the browser for sign-in and consent.

Cursor

Add to .cursor/mcp.json:

{ "mcpServers": { "harperharbor": { "url": "https://api.harperharbor.com/mcp" } } }

Codex

~/.codex/config.toml

[mcp_servers.harperharbor]
url = "https://api.harperharbor.com/mcp"

Any client

Use the streamable HTTP transport with the URL above. When the server answers 401, follow the WWW-Authenticate challenge: register a client at /oauth/register, run the authorization-code flow with PKCE, and retry with the Bearer token.

What the tools cover

Group	Examples	Notes
Cards	create a private card, patch profile / document / welcome, validate, submit for review	same ownership rules and quotas as the HTTP authoring endpoints
Worldbooks	create, add and update entries, bind to a card	keyword fields are arrays
Themes and previews	render a preview, validate a theme	output is a preview page the client can open
Conversation	start, send, read status	for testing a card the way a player would
Account	read usage and balance, read lane status	read-only

The exact tool list is discoverable from the server (tools/list) and is versioned with the platform, not with this page.

Rules for AI clients

• Never invent identifiers. Card, worldbook and conversation ids come from tool results.
• Do not paste secrets into tool arguments. The server already knows who you are from the token.
• Read before write. Fetch the current document before patching; patches merge with the existing document. Send only the fields you intend to change.
• Costs apply. Conversation tools debit the signed-in user’s wallet like any other call.

Skills

If your client supports skills (Claude Code, Codex), install the HarperHarbor skills so the model knows the workflow, the field limits and the review rules before it edits a card. See Skills.