> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai2fin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP authentication methods

> Set up OAuth JWT tokens or API keys to authenticate with the AI2Fin MCP server, including rate limits, scopes, and token generation steps.

# Finance MCP Authentication

AI2Fin Finance MCP Server supports **two authentication methods** for secure access to your financial data. Choose OAuth (JWT) for OAuth-based integrations or API keys for MCP Inspector, automation, and custom integrations.

## Quick Comparison

| Feature          | OAuth (JWT)                     | API Key                                          |
| ---------------- | ------------------------------- | ------------------------------------------------ |
| **Endpoint**     | `/mcp`                          | `/mcp/inspector`                                 |
| **Use Case**     | OAuth integrations              | Automation, testing, custom integrations         |
| **Write Access** | Full (with confirmation)        | Read-only (default), write with `mcp:full` scope |
| **Header**       | `Authorization: Bearer <token>` | `X-API-Key: <key>`                               |
| **Token Format** | OAuth bearer token              | API key with `mcp_` prefix                       |

<Info>
  Both endpoints are rate limited to keep the service fast and fair for everyone. If you hit a limit you'll receive a `429` response—wait for the window to reset and retry with backoff.
</Info>

## Authentication Methods

<Card title="Create API Key" icon="key" href="https://app.ai2fin.com/#/api" target="_blank">
  Generate a new API key in the AI2Fin dashboard. Opens in a new window.
</Card>

<Tabs>
  <Tab title="OAuth (JWT)">
    For OAuth-based integrations
  </Tab>

  <Tab title="API Key">
    For MCP Inspector, custom integrations, and testing
  </Tab>
</Tabs>

***

## OAuth Authentication

Used by the **`/mcp`** endpoint for OAuth-based integrations.

### How It Works

1. You authenticate via OAuth
2. You receive a bearer token
3. Include the token in the `Authorization: Bearer <token>` header
4. The server validates the token and resolves your account
5. Every operation is scoped to your account only

### Request Format

```http theme={null}
POST /mcp
Authorization: Bearer <your_oauth_token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}
```

### Use Cases

* OAuth-based integrations
* Custom integrations with OAuth
* Full write access (with confirmation for destructive operations)

***

## API Key Authentication

Used by the **`/mcp/inspector`** endpoint for MCP Inspector and custom integrations.

### How It Works

1. You generate an API key from your AI2Fin dashboard
2. Keys are stored securely (never in plaintext) and shown to you only once
3. Include the API key in the `X-API-Key: <key>` header
4. The server validates the key and resolves your account
5. Every operation is scoped to your account only

### Request Format

**Header Name:** `X-API-Key`

Include your API key in the `X-API-Key` header with all requests to the `/mcp/inspector` endpoint:

```http theme={null}
POST /mcp/inspector
X-API-Key: mcp_your_api_key
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}
```

**Alternative Header:** You can also use the `Authorization: Bearer` header format:

```http theme={null}
POST /mcp/inspector
Authorization: Bearer mcp_your_api_key
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}
```

<Tip>
  **Recommended:** Use `X-API-Key` header for MCP Inspector endpoints. Both header formats are supported, but `X-API-Key` is the standard for API key authentication.
</Tip>

### API Key Format

* **Prefix:** `mcp_`
* **Example:** `mcp_your_api_key`

### Generating API Keys

The easiest way to create an API key is from your AI2Fin dashboard:

<Card title="Create API Key" icon="key" href="https://app.ai2fin.com/#/api" target="_blank">
  Generate a new API key in the AI2Fin dashboard. Opens in a new window.
</Card>

You can also create a key programmatically with an authenticated request:

```bash theme={null}
POST /api/api-keys
Authorization: Bearer <your_oauth_token>
Content-Type: application/json

{
  "name": "MCP Inspector - Production",
  "scopes": ["mcp:full"],
  "expiresInDays": 90
}
```

**Response:**

```json theme={null}
{
  "id": "key_123",
  "key": "mcp_your_api_key",  // ⚠️ Only shown once!
  "name": "MCP Inspector - Production",
  "scopes": ["mcp:full"],
  "expiresAt": "2024-04-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "warning": "Save this key now - it will not be shown again!"
}
```

<Note>
  **Default Scope:** If you don't specify `scopes`, the key is read-only (`["mcp:read"]`). To grant write access, you must explicitly request the `mcp:full` scope, as shown in the example above.
</Note>

<Warning>
  **Save the `key` value immediately** - it's only shown once during creation. If lost, you must revoke and create a new key.
</Warning>

### API Key Scopes

* **`mcp:read`** - Read-only access to all MCP operations
* **`mcp:tools:list`** - List available tools
* **`mcp:tools:call`** - Execute tools (read-only)
* **`mcp:resources:read`** - Read resources
* **`mcp:full`** - Full access (read + write)

### Use Cases

* Automation and scripting
* Custom integrations
* Testing and development
* Read-only access (default)
* Write access (with `mcp:full` scope)

***

## User Isolation

<Warning>
  **Critical:** Every MCP operation is scoped to your authenticated account. There is no cross-account data access.
</Warning>

Whether you authenticate with OAuth or an API key, the server resolves the request to your account and returns only your data. Requests can never read or write another account's information.

***

## Error Responses

### Invalid Token

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "data": {
      "errorType": "INVALID_TOKEN",
      "message": "Invalid or expired authentication token"
    }
  }
}
```

### Missing/Invalid API Key

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "data": {
      "errorType": "INVALID_API_KEY",
      "message": "API key not found or has been revoked"
    }
  }
}
```

### Insufficient Scope

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 403,
    "message": "Forbidden",
    "data": {
      "errorType": "INSUFFICIENT_SCOPE",
      "message": "API key does not have permission for this operation"
    }
  }
}
```

***

## Common Issues & Solutions

<AccordionGroup>
  <Accordion title="Invalid Token Error" icon="key">
    **Error:** `401 Unauthorized - Invalid or expired authentication token`

    **Causes:**

    * JWT token has expired
    * Token was revoked
    * Token format is incorrect

    **Solutions:**

    * ✅ Re-authenticate via OAuth to get new token
    * ✅ Check token expiration time
    * ✅ Verify token is in correct format: `Bearer <token>`
    * ✅ Ensure token hasn't been revoked
  </Accordion>

  <Accordion title="API Key Not Found" icon="search">
    **Error:** `401 Unauthorized - API key not found or has been revoked`

    **Causes:**

    * API key was revoked
    * Key format is incorrect
    * Key has expired

    **Solutions:**

    * ✅ Generate new API key via `/api/api-keys`
    * ✅ Verify the key starts with the `mcp_` prefix
    * ✅ Check key expiration date
    * ✅ Ensure key hasn't been revoked
  </Accordion>

  <Accordion title="Insufficient Scope" icon="shield">
    **Error:** `403 Forbidden - API key does not have permission`

    **Causes:**

    * API key missing required scope
    * Attempting write operation with read-only key

    **Solutions:**

    * ✅ Check API key scopes: `mcp:read`, `mcp:tools:call`, `mcp:full`
    * ✅ For write operations, use key with `mcp:full` scope
    * ✅ Regenerate key with appropriate scopes
  </Accordion>

  <Accordion title="Rate Limit Exceeded" icon="gauge">
    **Error:** `429 Too Many Requests`

    **Causes:**

    * Too many requests in a short period
    * Burst limit exceeded

    **Solutions:**

    * ✅ Wait for the rate limit window to reset before retrying
    * ✅ Implement exponential backoff retry logic
    * ✅ Use batch operations to reduce request count
    * ✅ Check `X-RateLimit-Reset` header for reset time
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Store Keys Securely" icon="lock">
    Never commit API keys to version control. Use environment variables, secret management (AWS Secrets Manager, HashiCorp Vault), or secure configuration files.
  </Card>

  <Card title="Use Minimal Scopes" icon="shield">
    Grant only the minimum permissions needed. Use `mcp:read` for read-only access. Only grant `mcp:full` when write access is required.
  </Card>

  <Card title="Rotate Keys Regularly" icon="refresh">
    Rotate API keys periodically (every 90 days recommended). Revoke old keys immediately after generating new ones.
  </Card>

  <Card title="Use HTTPS Only" icon="lock">
    Always use HTTPS for API key transmission. Never send keys over HTTP. Validate SSL certificates in production.
  </Card>

  <Card title="Monitor Key Usage" icon="chart-line">
    Track API key usage patterns. Set up alerts for unusual activity. Review access logs regularly.
  </Card>

  <Card title="Separate Keys per Environment" icon="server">
    Use different API keys for development, staging, and production. Never share keys between environments.
  </Card>
</CardGroup>

## Keywords & Search Intent

**Primary Keywords:**

* Finance MCP authentication
* MCP API key
* Financial data API token
* MCP server authentication
* Expense tracking MCP API key
* Tax deduction MCP token

**User Intent Keywords:**

* "How to authenticate with MCP finance server"
* "Generate API key for financial MCP"
* "MCP authentication for ChatGPT integration"
* "API token for expense tracking MCP"
* "Financial data API authentication"

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/mcp/quickstart">
    Get started with authentication examples
  </Card>

  <Card title="Code Examples" icon="code" href="/mcp/examples">
    See authentication in action
  </Card>

  <Card title="API Reference" icon="server" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/mcp/tools-overview">
    Explore available financial tools
  </Card>
</CardGroup>