The MCP Endpoint: Stone Maps as a Tool

Stone Maps has an MCP server. If you have an MCP client — Claude Desktop, any tool that speaks the Model Context Protocol — you can point it at https://stnmps.com/api/mcp/mcp and use Stone Maps as a tool.

You can read your journal. Write entries. Start conversations with the Emissary. Find nearby posts by coordinate. All from inside another AI.

Building it took about a day. But the interesting part wasn't the implementation — it was what it revealed about the product.

What MCP Is

The Model Context Protocol is a standard for AI tools. Instead of building a bespoke plugin for every AI assistant, you implement one MCP server and any compliant client can use it. The protocol handles discovery (what tools exist, what parameters they take) and invocation (call this tool with these arguments, return the result).

Stone Maps uses the @modelcontextprotocol/sdk with the Web Standard Streamable HTTP transport — the MCP protocol version designed for stateless HTTP endpoints, not persistent WebSocket connections. This means the server runs inside a Next.js API route (/api/mcp/[transport]) and Vercel scales it like any other serverless function.

Authentication

Every MCP request carries a Bearer token in the Authorization header:

async function handle(req: NextRequest): Promise<Response> {
  const apiToken = (req.headers.get('authorization') ?? '').replace(/^Bearer\s+/, '');
  const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  const server = buildServer(apiToken, getApiUrl());
  await server.connect(transport);
  return transport.handleRequest(req);
}

The API token is your Stone Maps personal API token — the same kind you can generate from the settings screen. The MCP server proxies every tool call through the Stone Maps REST API using that token as a Bearer credential. It doesn't hold a privileged service account; it acts as you.

This means the MCP endpoint has the same permission scope as your account. You can only read your own private journal entries. You can only create posts as yourself. The access model is not different for AI callers than for browser callers.

The Tools

The MCP server exposes 17 tools:

System

• check_health — API health check (database, Redis, R2 status)

User

• get_user_profile — your account details

Self-pairs

• get_self_pairs — your paired stones

Posts

• get_journal_posts — paginated journal entries, up to 100 at a time
• create_post — new journal entry with optional visibility (private, public, team)
• search_posts — search by query string

Stones

• list_stones — all stones you own
• get_stone_details — a single stone by ID

Conversations

• list_conversations — your Emissary conversation history
• start_conversation — begin a new Emissary session, optionally with coordinates

Map

• get_nearby_posts — public posts within a radius (default 1km, max 50km) of a coordinate
• get_map_posts — public posts within a bounding box

Teams

• list_teams — teams you belong to

Campaigns

• list_campaigns — campaigns for a team

Tokens

• list_tokens — your API tokens (metadata only, never the raw token)
• create_token — generate a new API token
• delete_token — revoke a token by ID

What This Means for the Product

Building the MCP endpoint forced a useful audit. Each tool required a clear, one-sentence description of what it does. That process surfaced inconsistencies in the REST API design — places where two endpoints did similar things with different parameter shapes, or where a logical tool didn't exist yet.

More interesting was the question of what kind of thing Stone Maps is when accessed through a tool interface.

The journal — your private record of places and moments — becomes queryable. An AI assistant can ask "what did I write about last Tuesday?" or "find my posts from near the coast." The Emissary conversation history becomes a data source, not just a UI element.

This is fine. It's arguably one of the more interesting use cases: your journal as a research context for another AI that's helping you think about something. But it's also a thing to be thoughtful about. Private posts are private because you decided they were. The MCP endpoint respects that. But the interface still feels different — more legible, more extractable — than typing into a text box.

The start_conversation tool is the one that interests me most. You can initiate an Emissary conversation with an explicit location — latitude and longitude — without actually being there. From a desktop MCP client, you could start a conversation situated at a place you remember, not a place you're standing. The Emissary doesn't know the difference.

Whether that's a feature or a problem depends on what you think the journal is for.

Using It

To connect Stone Maps to Claude Desktop, add to your MCP config:

{
  "mcpServers": {
    "stone-maps": {
      "type": "http",
      "url": "https://stnmps.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Generate your API token from Settings → API Tokens. The token is shown once — copy it before closing the dialog.

From there, any MCP-capable assistant can call into your Stone Maps account. What you do with that is up to you.