# PlugMCP auth.md

How an agent authenticates with PlugMCP. Three surfaces, three rules. A person signs in to create keys; agents only use them.

## Audience

Agents and MCP clients that call the PlugMCP directory, the directory REST API, or a server a customer hosts on the PlugMCP gateway.

## Directory MCP: https://plugmcp.ai/mcp-server

- No key needed. Without one: 50 tool calls a day per IP address.
- Optional directory key raises the limit: 500 a day on a free account, 20,000 a day on a paid plan.
- Get a key: a person signs in at https://plugmcp.ai/app and creates a directory key (steps at https://plugmcp.ai/directory-mcp). Keys start with `pb_live_` and are shown once. Limits are per organization and reset at 00:00 UTC.
- Send it on every request as `Authorization: Bearer <key>`. `X-PlugMCP-Key: <key>` and `X-API-Key: <key>` also work.
- A wrong or revoked key gets a note in the tool result and the no-key limit, not a silent upgrade.
- Over the limit, the tool result says so and where to get a key or a higher plan.
- Server card: https://plugmcp.ai/.well-known/mcp/server-card.json

## Directory REST API: https://plugmcp.ai/api/v1/servers

- Read-only and public. No credentials.
- Description: https://plugmcp.ai/openapi.json

## Hosted servers: https://mcp.plugmcp.ai/s/{slug}

Servers that PlugMCP customers build or host. Each one belongs to an organization.

- API key: the owner creates a key in the PlugMCP dashboard. It starts with `pb_live_`, is shown once, and PlugMCP stores only its SHA-256 hash. A key can be scoped to one server.
- Send it as `Authorization: Bearer <key>`. Missing or invalid keys get HTTP 401; a key for another server or organization gets 403; too many calls get 429.
- Servers marked public accept calls without a key, rate limited per IP.
- OAuth 2.1 for MCP clients that support it:
  - Protected resource metadata (RFC 9728): https://mcp.plugmcp.ai/.well-known/oauth-protected-resource/s/{slug}
  - Authorization server metadata (RFC 8414): https://mcp.plugmcp.ai/.well-known/oauth-authorization-server
  - Authorization code with PKCE (S256), scope `mcp`. Dynamic client registration at https://mcp.plugmcp.ai/oauth/register.
  - The person approving access signs in to PlugMCP on the authorize page. The issued token works like a server-scoped key.

## What agents cannot do

- Create, list, or revoke keys without a signed-in person.
- Use a directory key on hosted servers, or a hosted server key on the directory. They are separate.

## Help

- Directory MCP guide: https://plugmcp.ai/directory-mcp
- Connect a hosted server: https://plugmcp.ai/docs/connect
- Contact: https://plugmcp.ai/contact