# MCP server

The Model Context Protocol endpoint, its tools, how to connect from Claude, Cursor and other clients, and the one rule about keys.

Endpoint: `https://tapmy.link/mcp` — Streamable HTTP, stateless, no OAuth. The tools are thin wrappers over the same functions the HTTP API calls, so anything documented here holds there.

## Connecting

Claude Code:

```bash
claude mcp add --transport http tapmy https://tapmy.link/mcp
# with a key for an existing account:
claude mcp add --transport http tapmy https://tapmy.link/mcp --header "Authorization: Bearer tapmy_sk_…"
```

Cursor, Windsurf, Claude Desktop and anything that reads a JSON config:

```json
{
  "mcpServers": {
    "tapmy": {
      "url": "https://tapmy.link/mcp",
      "headers": { "Authorization": "Bearer tapmy_sk_…" }
    }
  }
}
```

Clients that only speak stdio can bridge with `npx mcp-remote https://tapmy.link/mcp --header "Authorization: Bearer …"`.

## The rule about keys

Most clients fix their headers when they connect. `create_page` returns a key for a *new* account, and the session that called it cannot add that key to its headers. So every tool that needs an account also accepts an `api_key` argument; a header, when present, wins. Pass the key you were given back into the tools you call next.

## Tools

| Tool | Needs a key | Does |
| --- | --- | --- |
| `check_username` | no | Free / taken / invalid, with suggestions. |
| `list_templates` | no | The ten templates with descriptions and fit. |
| `list_platforms` | no | Platform ids for social blocks. |
| `validate_page` | no | Dry run of `create_page`. |
| `create_page` | no (or yes, to add to an account) | The one-shot create; returns key, claim link, URL, handover message. |
| `whoami` | yes | Account, pages, remaining slots. |
| `get_page` | yes | A page's full document. |
| `update_page` | yes | PATCH semantics on any fields. |
| `add_block` | yes | Append one block without resending the list. |
| `set_avatar_from_url` | yes | Fetch, store and set the photo in one step. |
| `import_links_from_url` | yes | Append the links found on a public link page. |
| `publish` | yes | Publish or unpublish. |
| `get_stats` | yes | Views, uniques, taps, daily series. |
| `get_claim_link` | yes | A fresh claim link for a provisional account. |

Every tool returns JSON as text and the same object as `structuredContent`. Errors come back as `isError: true` with the same `{ code, hint }` envelope as HTTP.

## Skill

A skill file for agents that install procedures rather than tools is at [https://tapmy.link/skill.md](https://tapmy.link/skill.md).

---
Part of the [Tapmy.link agent documentation](https://tapmy.link/documentation/agents.md). Canonical: https://tapmy.link/documentation/agents/mcp.md