Connect an agent

1. Mint a token

Settings → MCP → New token. Pick the scopes this agent needs and nothing more; see Choose the right scopes if you are unsure.

The token is shown once, in the form mm_pat_<id>_<secret>. Copy it then - it is stored hashed and cannot be shown again. If you lose it, revoke it and mint another.

2. Point your client at the server

For an MCP client that reads a JSON config:

{
  "mcpServers": {
    "makermap": {
      "url": "https://api.makermap.dev/api/mcp",
      "headers": { "Authorization": "Bearer mm_pat_..." }
    }
  }
}

The transport is Streamable HTTP and the server is stateless, so there is no session to keep alive and no reconnect logic to write. Running locally, the URL is http://localhost:4591/api/mcp.

3. Check what it can see

Ask the client to list its tools. You should get back only the tools your scopes cover - discovery is permission-aware, so the list is the honest answer to "what can this agent do", not a catalogue with locked doors in it.

Two calls worth making first:

• whoami - confirms the token resolves and shows whose it is.
• get_workspace_overview - the portfolio in one call.

4. Install the working environment

This is the step most people skip, and it is the one that puts your rules and skills on the machine.

get_workspace_setup lists the setup profiles this workspace can install, their pinned versions and the recommended one. apply_setup_profile with dryRun: true shows the plan; without it, applies. makermap assembles the package - rules, skills, agent profiles, MCP hints - and your client writes it to the machine. makermap never touches a file.

It also needs a wider token than the reads above: setup_profiles:read plus instructions:read and assets:read. If the tool is missing from your list, that is why - and it is why the MCP server instructions mention the chain only when your token can actually follow it.

Rules arrive through the sets a profile pins. A rule that is still a draft is not in any of them: drafts reach no agent at all until somebody publishes them, which is a deliberate act on the rule's own page.

Then: give it the context, not a tour

The single most useful call is get_product_context. It returns a product's whole working picture - the why fields, the stage, open decisions, the board, recent activity, knowledge, links - budgeted to fit a context window, instead of the fifteen calls an agent would otherwise make to assemble the same thing badly.

Pass back the contextRevision it returns and the next call gives you only what changed.

If something refuses

Read the refusal. Every one carries a code, a message and a hint naming the next call that would work. The ones you are most likely to see first are in the error reference.