Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicobailon/pi-mcp-adapter/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication Types

Pi MCP Adapter supports two authentication methods for HTTP-based MCP servers:
  • Bearer Token - Static token passed in the Authorization header
  • OAuth - OAuth 2.0 flow with token storage and manual refresh

​
Bearer Token Authentication

​
Direct Token

Provide the bearer token directly in the configuration:
​
auth
string
required
Set to "bearer" to enable bearer token authentication
​
bearerToken
string
The actual bearer token value
{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com/mcp",
      "auth": "bearer",
      "bearerToken": "sk-1234567890abcdef"
    }
  }
}
Storing tokens directly in config files is not recommended for production. Use environment variables instead.

​
Environment Variable

Reference an environment variable containing the token:
​
bearerTokenEnv
string
Name of the environment variable containing the bearer token
{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "API_TOKEN"
    }
  }
}
Then set the environment variable before running Pi: 
export API_TOKEN="sk-1234567890abcdef"
pi

​
How Bearer Tokens Work

The adapter adds the token to every HTTP request: 
Authorization: Bearer sk-1234567890abcdef

​
OAuth Authentication

​
Configuration

​
auth
string
required
Set to "oauth" to enable OAuth authentication
{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": "oauth"
    }
  }
}

​
OAuth Flow

1

Configure Server

Add the server to your mcp.json with "auth": "oauth"
2

Initiate OAuth

Run the OAuth setup command:
/mcp-auth <server-name>
3

Obtain Tokens Externally

Pi MCP Adapter does not provide a browser-based OAuth flow. You must obtain tokens through the provider’s OAuth process externally (e.g., via their web interface, CLI tool, or authorization endpoint).
4

Store Tokens

Manually create the token file at:
~/.pi/agent/mcp-oauth/<server-name>/tokens.json
5

Connect

The adapter will read the stored tokens and use them for authentication:
/mcp reconnect <server-name>

​
Token Storage Format

Tokens are stored in: 
~/.pi/agent/mcp-oauth/<server-name>/tokens.json
Required format: 
{
  "access_token": "ya29.a0AfH6SMBx...",
  "token_type": "bearer",
  "refresh_token": "1//0gHZ9K8vQz...",
  "expires_in": 3600,
  "expiresAt": 1234567890000
}
​
access_token
string
required
The OAuth access token
​
token_type
string
default:"bearer"
Token type (usually "bearer")
​
refresh_token
string
OAuth refresh token (optional, not currently used for automatic refresh)
​
expires_in
number
Token lifetime in seconds (optional)
​
expiresAt
number
Absolute expiration timestamp in milliseconds (optional). If set, the adapter checks expiration before using the token.

​
Token Expiration

The adapter checks token expiration if expiresAt is present in the token file: 
if (Date.now() > expiresAt) {
  // Token expired - server shows "needs-auth" status
}
Automatic token refresh is not currently implemented. When tokens expire, you must manually refresh them and update the tokens.json file.

​
Manual Token Refresh

When your OAuth tokens expire:
1

Check Server Status

Run /mcp to see which servers show “needs-auth” status
2

Refresh Tokens Externally

Use the provider’s OAuth flow or CLI to obtain new tokens
3

Update Token File

Replace the contents of ~/.pi/agent/mcp-oauth/<server-name>/tokens.json with the new tokens
4

Reconnect

/mcp reconnect <server-name>

​
Custom Headers

For servers that require additional authentication headers beyond OAuth or bearer tokens:
​
headers
object
Custom HTTP headers included in every request
{
  "mcpServers": {
    "custom-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${API_KEY}",
        "X-Custom-Header": "value"
      }
    }
  }
}
Header values support ${VAR} environment variable interpolation, just like the env field.

​
Complete Examples

{
  "mcpServers": {
    "github-api": {
      "url": "https://api.github.com/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "GITHUB_TOKEN",
      "headers": {
        "Accept": "application/vnd.github.v3+json"
      }
    }
  }
}

​
Security Best Practices

Never commit tokens or API keys to version control. Use environment variables or exclude mcp.json from git if it contains sensitive data.

​
Recommendations

  1. Use environment variables for all tokens and keys: 
    {
  "bearerTokenEnv": "API_TOKEN"
}
  2. Protect token storage directory: 
    chmod 700 ~/.pi/agent/mcp-oauth
chmod 600 ~/.pi/agent/mcp-oauth/*/tokens.json
  3. Rotate tokens regularly even if they haven’t expired
  4. Use least-privilege tokens with only the permissions needed for the MCP server
  5. Monitor token expiration and set up reminders to refresh before expiry

​
Troubleshooting

​
Server Shows “needs-auth” Status

OAuth servers:
  • Check if ~/.pi/agent/mcp-oauth/<server>/tokens.json exists
  • Verify the token file has valid JSON format
  • Check if expiresAt timestamp has passed
  • Refresh tokens and update the file
Bearer token servers:
  • Verify the environment variable is set: echo $API_TOKEN
  • Check that the token value is correct
  • Ensure bearerTokenEnv matches the actual variable name

​
Token Validation Errors

The adapter requires access_token to be present and non-empty: 
{
  "access_token": "ya29.a0AfH6SMBx..."
}
If missing or invalid, the server won’t connect.

​
Automatic Refresh Not Working

This is expected behavior. Automatic token refresh is not currently implemented. You must manually refresh tokens when they expire.

​
Limitations

  • No browser-based OAuth flow - Tokens must be obtained externally
  • No automatic token refresh - Manual refresh required when tokens expire
  • Refresh tokens are stored but not used - Future feature
  • No cross-session token sharing - Each Pi session manages its own tokens

​
Next Steps

Server Setup

Configure MCP servers with different transports

Global Settings

Set defaults for toolPrefix, idleTimeout, and directTools

Build docs developers (and LLMs) love

Get started for freeTalk to us