Docs MCP server

The docs MCP server lets an AI coding assistant search and read these docs while it writes code. Instead of recalling an iam.api method from training data, the assistant calls lookup_api_method and gets the signature, HTTP route, and behaviour of the version the docs were built from.

The server speaks the Model Context Protocol over Streamable HTTP at https://better-iam.com/api/mcp. It is read-only, needs no sign-in, and keeps no session between requests.

Setup

claude mcp add --transport http better-iam-docs https://better-iam.com/api/mcp

claude mcp add --transport http --scope project better-iam-docs https://better-iam.com/api/mcp

{
  "mcpServers": {
    "better-iam-docs": { "type": "http", "url": "https://better-iam.com/api/mcp" }
  }
}

Use the better-iam-docs MCP server: what does iam.api.bindings.create take, and which HTTP route serves it?

npx @modelcontextprotocol/inspector

Tools

The server registers six tools. Its instructions tell the assistant when to use search, get_page, and the three lookup tools.

search

Full-text search over every page, the same index as the search dialog on the site. Use it when you know what you want to do but not which page covers it, for example "temporary access expiring binding". Each result's url can be passed to get_page (drop any #heading fragment).

list_pages

Lists every page in sidebar order, with its URL and description. The URLs are site paths such as /docs/authorization/roles, which is the form get_page accepts.

get_page

Returns one page as Markdown, the same text as /docs/<page>.md (see Markdown for one page). Pass the path, for example /docs/authorization/policies, without .md. An unknown path returns an error result page not found: <url>.

lookup_api_method

Returns one iam.api method:

• the curated description of what it does, the permission it checks, and the errors it throws;
• its HTTP route under /api/iam and whether it needs a credential, or that it is not routed and runs only in server code;
• its TypeScript signature;
• a link to its section in the API reference.

The input is group.method, for example groups.addMember. A leading iam.api. or client. is ignored, and matching is case-insensitive. An unknown group returns the list of groups, and an unknown method returns the methods of its group, so an assistant can correct itself.

lookup_export

Explains a function, hook, component, class, or constant that a package exports. The input is the export name, optionally after its package: useSession, @better-iam/react useSession, or better-iam/react#useSession. A package name also covers its other entry points, so @better-iam/next useSession finds the export of @better-iam/next/client. When several entry points export the name, each one is listed.

lookup_error_code

Explains an IamError code such as ACCESS_DENIED or RATE_LIMITED: its HTTP status, what it means, how to handle it, and example messages, with a link to the error reference. Matching is case-insensitive.

Use it well

• Ask for lookups explicitly at first ("look up every iam.api call you use with lookup_api_method"); most assistants then keep using the tools for the rest of the session.
• Pair the server with the agent skill: the skill gives the setup order and rules up front, and the server answers the exact questions that come up while coding.
• Add a line to your repository's agent instructions so every session uses it; see Prompts and AGENTS.md.

Troubleshooting

Next steps