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	MCP Inspector, automation, testing
Rate Limit	200 req/15min per user	50 req/15min per key
Write Access	Full (with confirmation)	Read-only (default), write with `mcp:full` scope
Header	`Authorization: Bearer <token>`	`X-API-Key: <key>`
Token Format	JWT (from OAuth provider)	`mcp_<64 hex chars>`

Authentication Methods

Create API Key

Generate a new API key in the AI2Fin dashboard. Opens in a new window.

OAuth (JWT)
API Key

For OAuth-based integrations

OAuth Authentication

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

How It Works

User authenticates via OAuth (Zitadel)
OAuth provider issues JWT token
JWT token included in Authorization: Bearer <token> header
Server validates token and extracts userId
All operations scoped to that userId

Request Format

POST /mcp
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

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

Rate Limiting

Per-user limit: 200 requests per 15 minutes
Burst size: 30 requests
Key: mcp_user_{userId}

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

User generates API key via /api/api-keys endpoint
API key stored as SHA-256 hash (never plaintext)
API key included in X-API-Key: <key> header
Server validates key hash and extracts userId from key record
All operations scoped to that userId

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:

POST /mcp/inspector
X-API-Key: mcp_a1b2c3d4e5f6...
Content-Type: application/json

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

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

POST /mcp/inspector
Authorization: Bearer mcp_a1b2c3d4e5f6...
Content-Type: application/json

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

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.

API Key Format

Prefix: mcp_
Length: 64 hex characters
Example: mcp_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Generating API Keys

Create your own API key using your JWT token:

POST /api/api-keys
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

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

Response:

{
  "id": "key_123",
  "key": "mcp_a1b2c3d4...",  // ⚠️ 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!"
}

Default Scope: If you don’t specify scopes, it defaults to ["mcp:full"] for full MCP Inspector capability.

Save the key value immediately - it’s only shown once during creation. If lost, you must revoke and create a new key.

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)

Rate Limiting

Per-key limit: 50 requests per 15 minutes
Burst size: 10 requests
Key: inspector_{apiKeyId} or inspector_ip_{ip} (fallback)

Use Cases

MCP Inspector tool
Custom integrations
Testing and development
Read-only access (default)
Write access (with mcp:full scope)

User Isolation

Critical: All MCP operations are scoped to the authenticated user. There is zero cross-user data access.

How It Works

OAuth: userId extracted from JWT token claims
API Key: userId from API key record (apiKey.userId)
Context: All tool executions receive context.userId
Database Queries: All queries include WHERE userId = context.userId

Error Responses

Invalid Token

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

Missing/Invalid API Key

{
  "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

{
  "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

Invalid Token Error

Error: 401 Unauthorized - Invalid or expired authentication tokenCauses:

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

API Key Not Found

Error: 401 Unauthorized - API key not found or has been revokedCauses:

API key was revoked
Key format is incorrect
Key has expired

Solutions:

✅ Generate new API key via /api/api-keys
✅ Verify key format: mcp_<64 hex characters>
✅ Check key expiration date
✅ Ensure key hasn’t been revoked

Insufficient Scope

Error: 403 Forbidden - API key does not have permissionCauses:

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

Rate Limit Exceeded

Error: 429 Too Many RequestsCauses:

Too many requests in 15-minute window
Burst limit exceeded

Solutions:

✅ Wait for rate limit window to reset (15 minutes)
✅ Implement exponential backoff retry logic
✅ Use batch operations to reduce request count
✅ Check X-RateLimit-Reset header for reset time

Best Practices

Store Keys Securely

Never commit API keys to version control. Use environment variables, secret management (AWS Secrets Manager, HashiCorp Vault), or secure configuration files.

Use Minimal Scopes

Grant only the minimum permissions needed. Use mcp:read for read-only access. Only grant mcp:full when write access is required.

Rotate Keys Regularly

Rotate API keys periodically (every 90 days recommended). Revoke old keys immediately after generating new ones.

Use HTTPS Only

Always use HTTPS for API key transmission. Never send keys over HTTP. Validate SSL certificates in production.

Monitor Key Usage

Track API key usage patterns. Set up alerts for unusual activity. Review access logs regularly.

Separate Keys per Environment

Use different API keys for development, staging, and production. Never share keys between environments.

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

Quickstart Guide

Get started with authentication examples

Code Examples

See authentication in action

API Reference

Complete API documentation

Tools Overview

Explore available financial tools

Getting Started

Authentication

Tools Reference

Integration

​Finance MCP Authentication

​Quick Comparison

​Authentication Methods

Create API Key

​OAuth Authentication

​How It Works

​Request Format

​Rate Limiting

​Use Cases

​API Key Authentication

​How It Works

​Request Format

​API Key Format

​Generating API Keys

​API Key Scopes

​Rate Limiting

​Use Cases

​User Isolation

​How It Works

​Error Responses

​Invalid Token

​Missing/Invalid API Key

​Insufficient Scope

​Common Issues & Solutions

​Best Practices

Store Keys Securely

Use Minimal Scopes

Rotate Keys Regularly

Use HTTPS Only

Monitor Key Usage

Separate Keys per Environment

​Keywords & Search Intent

​Next Steps

Quickstart Guide

Code Examples

API Reference

Tools Overview

Finance MCP Authentication

Quick Comparison

Authentication Methods

OAuth Authentication

How It Works

Request Format

Rate Limiting

Use Cases

API Key Authentication

How It Works

Request Format

API Key Format

Generating API Keys

API Key Scopes

Rate Limiting

Use Cases

User Isolation

How It Works

Error Responses

Invalid Token

Missing/Invalid API Key

Insufficient Scope

Common Issues & Solutions

Best Practices

Keywords & Search Intent

Next Steps