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:

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:

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:

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.