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

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.

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

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

Request Format

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

You generate an API key from your AI2Fin dashboard
Keys are stored securely (never in plaintext) and shown to you only once
Include the API key in the X-API-Key: <key> header
The server validates the key and resolves your account
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:

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:

POST /mcp/inspector
Authorization: Bearer mcp_your_api_key
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_
Example: mcp_your_api_key

Generating API Keys

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

Create API Key

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

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

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

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

Response:

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

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.

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)

Use Cases

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

User Isolation

Critical: Every MCP operation is scoped to your authenticated account. There is no cross-account data access.

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

{
  "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 the key starts with the mcp_ prefix
✅ 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 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

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

​Finance MCP Authentication

​Quick Comparison

​Authentication Methods

Create API Key

​OAuth Authentication

​How It Works

​Request Format

​Use Cases

​API Key Authentication

​How It Works

​Request Format

​API Key Format

​Generating API Keys

Create API Key

​API Key Scopes

​Use Cases

​User Isolation

​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

Use Cases

API Key Authentication

How It Works

Request Format

API Key Format

Generating API Keys

API Key Scopes

Use Cases

User Isolation

Error Responses

Invalid Token

Missing/Invalid API Key

Insufficient Scope

Common Issues & Solutions

Best Practices

Keywords & Search Intent

Next Steps