Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.instapods.com/llms.txt

Use this file to discover all available pages before exploring further.

MCP connections authenticate via OAuth 2.0 with PKCE (Proof Key for Code Exchange). This is handled automatically by your AI client — you just need to approve access in the browser.

​
How It Works

When an AI client connects to the InstaPods MCP server:
1

Discovery

The client hits POST /api/mcp and receives a 401 response with a WWW-Authenticate header pointing to the OAuth metadata.
2

Client Registration

The client auto-registers itself via RFC 7591 Dynamic Client Registration at /api/oauth/register.
3

Authorization

Your browser opens the InstaPods authorization page. You log in (if needed) and select which team to grant access to.
4

Token Exchange

The client exchanges the authorization code for an access token using PKCE verification.
5

Connected

The AI assistant can now call MCP tools scoped to your selected team.

​
OAuth Endpoints

EndpointPathDescription
Authorization Server MetadataGET /.well-known/oauth-authorization-serverRFC 8414 discovery
Protected Resource MetadataGET /.well-known/oauth-protected-resourceRFC 9728 discovery
Dynamic Client RegistrationPOST /api/oauth/registerRFC 7591 — public clients
AuthorizationGET /oauth/authorizeBrowser-based user approval
Token ExchangePOST /api/oauth/tokenCode → access token

​
Token Lifetime

  • Access tokens are valid for 30 days
  • When a token expires, your AI client will re-trigger the OAuth flow
  • You can revoke access by logging out of all sessions

​
Team Scoping

During authorization, you choose which team to grant access to. The MCP connection is scoped to that team — the AI can only see and manage pods belonging to that team. To switch teams, disconnect and reconnect the MCP server. You’ll be prompted to select a team again.

​
Security

  • PKCE required — all authorization requests must use S256 code challenge
  • No client secrets — AI clients are public OAuth clients (no secret stored)
  • HTTPS enforced — redirect URIs must be HTTPS (except localhost for development)
  • Single-use codes — authorization codes expire in 10 minutes and can only be used once

​
Troubleshooting

​
”Connection failed” or no browser window opens

  • Verify the MCP server URL is exactly https://app.instapods.com/api/mcp
  • Check that your browser allows pop-ups from your AI client
  • Try removing and re-adding the connector

​
Browser opens but shows an error

  • “Missing required OAuth parameters” — the AI client didn’t pass the required query parameters. Try disconnecting and reconnecting.
  • “code_challenge_method must be S256” — your client is using an unsupported PKCE method. Only S256 is supported.

​
Authenticated but tools return errors

  • “unauthorized” — your token may have expired. Disconnect and reconnect to get a fresh token.
  • “not a member of this team” — the pod belongs to a different team than the one you authorized. Reconnect and select the correct team.
  • “pod is not running” — the pod must be running for file, log, and exec operations. Use manage_pod with start first.

​
Token expired

Tokens are valid for 30 days. When your token expires, your AI client will automatically re-trigger the OAuth flow. If it doesn’t, remove and re-add the connector.

​
Switching teams

The MCP connection is scoped to the team you selected during authorization. To switch teams, disconnect the MCP server and reconnect — you’ll be prompted to select a team again.