# MCP Authentication

> OAuth 2.1 and Bearer token auth for the Portfolio Intel MCP server.

## OAuth 2.1 + PKCE

Any MCP client that supports OAuth 2.1 with PKCE can connect to `https://api.portfoliointel.co.in/mcp`, including Claude, ChatGPT, Cursor, VS Code, Codex, Windsurf and Hermes. The gateway serves discovery at `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server`. On the consent page you either enter your API key or choose **Create a free key and connect**. The page shows the host you will be redirected to.

A free key has the same limits as one from the [`register`](https://docs.portfoliointel.co.in/api-reference/register) endpoint: 30 credits for 7 days, and at most 3 new keys per network per hour. The button may show a Cloudflare Turnstile check first. After the key is created, a confirmation page shows a claim link. Open it to move the key into your Portfolio Intel account, which raises it to 100 credits and 30 days.

Clients identify themselves in one of two ways:

- **Client ID Metadata Document.** The `client_id` is an `https` URL that returns the client's metadata as JSON, with `client_id` equal to that URL, a `redirect_uris` list, and `token_endpoint_auth_method` of `none` if present. The gateway fetches it once and caches it for an hour. Documents over 5 KB, served from IP addresses or `localhost`, or returned through a redirect are rejected.
- **Dynamic Client Registration** at `/oauth/register` (RFC 7591). `redirect_uris` is required.

Accepted redirect URIs:

| Form | Example |
|---|---|
| `https` on any host | `https://vscode.dev/redirect` |
| `http` on loopback only | `http://127.0.0.1:33418/callback` |
| App scheme | `cursor://anysphere.cursor-retrieval/oauth/callback` |

URIs with a fragment, and `javascript:`, `data:`, `file:` and similar schemes, are rejected. At `/oauth/authorize` the `redirect_uri` must exactly match one the client registered or listed in its metadata document.

### Token lifetime

The agent never holds your API key. After you approve, the gateway issues:

- an **access token** (a signed JWT) that expires after **1 hour**, and
- a **refresh token** valid for **30 days**. It is single-use: each refresh returns a new refresh token and invalidates the old one, so a leaked token that has already been used can't be replayed.

Revoke access by deleting or rotating the underlying key in the developer dashboard.

## Bearer token

Claude Code, Cursor, and other token-capable clients configure a Bearer token directly:

```json
{
  "mcpServers": {
    "portfolio-intel": {
      "url": "https://api.portfoliointel.co.in/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}
```

## Scopes

| Scope | Allows |
|---|---|
| `parse` | `parse_cas`, `enrich`, `request_upload_url`, `generate_report`, `run_skill` |
| `enrich` | `enrich` only |
| none | `list_skills` (the skill catalog is public) |

A key with no scopes set gets `parse` and `enrich`. Keys from [`register`](https://docs.portfoliointel.co.in/api-reference/register) and the consent page get the same pair. Generate a narrower key in the developer dashboard.

Source: https://docs.portfoliointel.co.in/mcp/authentication/
