> ## 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 Authentication

> How OAuth authentication works for MCP connections.

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:

<Steps>
  <Step title="Discovery">
    The client hits `POST /api/mcp` and receives a `401` response with a `WWW-Authenticate` header pointing to the OAuth metadata.
  </Step>

  <Step title="Client Registration">
    The client auto-registers itself via [RFC 7591 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) at `/api/oauth/register`.
  </Step>

  <Step title="Authorization">
    Your browser opens the InstaPods authorization page. You log in (if needed) and select which team to grant access to.
  </Step>

  <Step title="Token Exchange">
    The client exchanges the authorization code for an access token using PKCE verification.
  </Step>

  <Step title="Connected">
    The AI assistant can now call MCP tools scoped to your selected team.
  </Step>
</Steps>

## OAuth Endpoints

| Endpoint                      | Path                                          | Description                                                                |
| ----------------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
| Authorization Server Metadata | `GET /.well-known/oauth-authorization-server` | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) discovery        |
| Protected Resource Metadata   | `GET /.well-known/oauth-protected-resource`   | [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) discovery        |
| Dynamic Client Registration   | `POST /api/oauth/register`                    | [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) — public clients |
| Authorization                 | `GET /oauth/authorize`                        | Browser-based user approval                                                |
| Token Exchange                | `POST /api/oauth/token`                       | Code → 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.