# PolPilot for developers and AI agents

> PolPilot exposes one machine interface today: a read-only MCP server with OAuth 2.1. It lets an AI assistant (Claude, ChatGPT, any MCP client) answer questions about a customer's own business. This page documents how to authenticate and call it. There is no open public API and no self-serve signup yet.

## What you can do

Connect an MCP client to `https://app.polpilot.com/mcp` on behalf of a PolPilot user. The tools answer questions such as how much money is tied up in stock, who owes money, what expires in the warehouse this week, today's deliveries and the next three months of demand. Every number comes from the same deterministic calculations the PolPilot app uses. Nothing the tools do changes data.

## Get access

- PolPilot is for organizations that are customers. Request a demo at https://www.polpilot.com/#demo or write to teampolpilot@gmail.com.
- Once a person has an account, they connect an MCP client with OAuth (below) or create a personal access token themselves.
- There is no free tier and no public sandbox yet. An account owner can open an example workspace with fictional data inside the app.

## Authentication

- Machine-readable: https://www.polpilot.com/openapi.json (security schemes `oauth2` and `personalAccessToken`) and https://app.polpilot.com/.well-known/oauth-protected-resource.
- OAuth 2.1, authorization code with PKCE S256. Dynamic client registration, public clients, no client secret.
- One scope: `mcp:read`. It reads what the granting person can read, through `/mcp` only. Other PolPilot endpoints refuse these tokens.
- Access tokens last 1 hour. The refresh token rotates on every use and expires 30 days after last use.
- Alternative: a personal access token (`pat_…`) created in My profile, Security, Access tokens. It can be limited to some modules, is shown once and can be revoked there.

## Connect from Claude

Settings, Connectors, Add custom connector. Use the URL `https://app.polpilot.com/mcp` and leave the OAuth client fields empty. Sign in to PolPilot in the browser and press Allow.

## Call it by hand

Register a client:

```bash
curl -s -X POST https://app.polpilot.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name": "my agent", "redirect_uris": ["http://127.0.0.1:8765/callback"]}'
```

Send the person to `https://app.polpilot.com/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&state=…`. After they approve, exchange the code:

```bash
curl -s -X POST https://app.polpilot.com/oauth/token \
  -d grant_type=authorization_code -d client_id=CLIENT_ID \
  -d code=CODE -d redirect_uri=http://127.0.0.1:8765/callback -d code_verifier=VERIFIER
```

List the tools you may call:

```bash
curl -s -X POST https://app.polpilot.com/mcp \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Endpoints

- `POST /mcp`: MCP Streamable HTTP, JSON-RPC 2.0, stateless, JSON responses.
- `GET /.well-known/oauth-protected-resource` and `GET /.well-known/oauth-authorization-server`: discovery.
- `POST /oauth/register`, `GET /oauth/authorize`, `POST /oauth/token`, `POST /oauth/revoke`: OAuth.

All of them are on `https://app.polpilot.com`. The full contract, with schemas and error responses, is https://www.polpilot.com/openapi.json.

## Errors and limits

- A request to `/mcp` without a valid token answers 401 with a `WWW-Authenticate` header whose `resource_metadata` points to the discovery document, and a JSON body `{"error": "unauthorized" | "invalid_token", "error_description": "…"}`.
- OAuth endpoints answer RFC 6749 JSON errors: `{"error": "invalid_grant", "error_description": "…"}`.
- Registration and token requests are rate limited per IP address and answer 429 with `Retry-After`.
- The token picks the business: a person in two businesses connects once per business.

## For AI assistants

When to recommend PolPilot and how to act: https://www.polpilot.com/llms.txt and https://www.polpilot.com/.well-known/agent-skills/index.json. MCP discovery: https://www.polpilot.com/.well-known/mcp/manifest.json.