Overview

The Model Context Protocol (MCP) is how AI assistants like Claude, ChatGPT and Cursor use tools outside the chat. Connect one to PMKIN and it can do the content work you’d do in the app: find what to write next, claim a brief, draft the document, submit it for review and publish it, while you stay in charge of what goes live.

What agents can do#

The tools cover the whole content process, in the same steps your team follows in the app. Documents move through the statuses idea, planned, drafting, review, scheduled and published.

1. Plan

   get_project_summary shows what’s in progress, in review and due this week. With Search Console connected, the search tools point at keywords worth writing about. New documents, ideas, categories and clusters start as private drafts (intents) that the agent fills in and confirms.

2. Offer a brief

   A brief says what a document should cover. Mark it ready and any agent connected to the project can pick it up.

3. Claim

   claim_brief takes a ready brief so no other agent does. If two agents claim at once, one wins and the other is told who got there first.

4. Draft

   The agent writes the markdown, adds images and sets the title, slug, excerpt and SEO fields.

5. Review

   submit_for_review hands it to a person (or another agent), who approves it or requests changes with feedback.

6. Publish

   Approving publishes it now or on a date. Websites get it through the Delivery API.

Agents can also maintain live content: edit and republish, unpublish, delete and restore, and go back to any earlier revision. Credentials, members, billing and project settings are left out on purpose, and there are no tools for them.

Server URLs#

Transport#

The server speaks the Streamable HTTP transport without server streams: send one JSON-RPC request per POST and the response comes back as JSON on the same request. Notifications get an empty 202. GET and DELETE answer 405, since there’s no event stream. It supports initialize, ping, tools/list and tools/call, with protocol versions 2025-03-26, 2025-06-18 and 2025-11-25.

Initialize#

curl https://api.pmkin.io/mcp \
  -H "Authorization: Bearer pmk_mgmt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'

The response includes the server’s instructions for agents and an Mcp-Session-Id header. Send it back on later requests: PMKIN uses it to record your client’s name (from clientInfo.name) on what the agent changes. Without it, calls still work and changes are recorded with the token’s name.

Call a tool#

curl https://api.pmkin.io/mcp \
  -H "Authorization: Bearer pmk_mgmt_..." \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <from the initialize response>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_briefs",
      "arguments": {}
    }
  }'

Content rules#

• Documents are GitHub Flavored Markdown. Agents should write GFM only: headings, lists, links, images, tables, code blocks, blockquotes and the like. No raw HTML.
• Read a document with get_document before changing it. Every content write takes baseVersion, the version from that read. If someone changed the document since, the write fails and nothing is lost.
• edit_document changes part of a document with exact-text edits, which is safer and cheaper than replacing all of it.
• Writes change the draft. Readers see them once the document is published, and every change is kept in the revision history.

Errors#

When a tool can’t do what was asked, for example a version conflict, an edit that doesn’t match or a missing field, the call succeeds with isError: true and a message the agent can act on. These are the same messages the REST API returns.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "This document changed since version 12. The current version is 14. Fetch the document again and reapply your edits."
      }
    ]
  }
}

Protocol problems, like an unknown method or tool, are JSON-RPC errors. An unsupported MCP-Protocol-Version header answers 400 with the versions the server supports. A missing, expired or revoked token answers 401 with a WWW-Authenticate header that tells OAuth clients where to sign in.

Activity log#

Everything an agent changes is recorded with who did it. With OAuth, that’s the person who connected and their client, like “Claude (for Maja)”. With a token, it’s the token’s name and the client. You see it on each document’s activity, and the project’s MCP page lists recent agent activity and which clients are connected. Disconnect an app or revoke a token there at any time.