Authentication

Configure OAuth and bearer token authentication for HTTP-based MCP servers

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

Bearer Token (Env Var)

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