Skip to main content
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

​
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.