MCP Authentication

Configure authentication for MCP server connections

MCP servers often require authentication to access their tools. xiantong supports several authentication methods to securely connect to protected servers.

Authentication Types#

The authType field in your MCP source configuration determines how authentication is handled:

OAuth Authentication#

For servers that support OAuth, set authType to "oauth":

{
"type": "mcp",
"name": "GitHub",
"tagline": "GitHub repository access",
"icon": "https://github.com/favicon.ico",
"mcp": {
"transport": "http",
"url": "https://api.githubcopilot.com/mcp/",
"authType": "oauth"
}
}

When you first use this source:

1. xiantong detects OAuth authentication is required
2. A browser window opens for you to authorize access
3. After approval, you’re redirected back to the application
4. The OAuth token is stored securely for future use

Token Refresh#

OAuth tokens are automatically refreshed when they expire. If a refresh fails, you’ll be prompted to re-authenticate.

Bearer Token Authentication#

For servers that use static API keys or bearer tokens, set authType to "bearer":

{
"type": "mcp",
"name": "Exa Search",
"tagline": "Neural search for the web",
"icon": "https://exa.ai/favicon.ico",
"mcp": {
"transport": "http",
"url": "https://mcp.exa.ai/mcp",
"authType": "bearer"
}
}

When you first use this source, you’ll be prompted for your API key:

The "Exa Search" source needs credentials.
Enter bearer token: ****************************

Stored securely

Credentials are stored encrypted locally in ~/.xiantong/credentials.enc, not in your configuration files.

Public Servers#

For servers that don’t require authentication, set authType to "none":

{
"type": "mcp",
"name": "Public Tools",
"tagline": "Publicly available tools",
"mcp": {
"transport": "http",
"url": "https://public.example.com/mcp",
"authType": "none"
}
}

No additional configuration needed.

Local Servers (Stdio)#

Local servers using stdio transport typically don’t require network authentication:

{
"type": "mcp",
"name": "Local MCP",
"tagline": "MCP Description",
"mcp": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "@package/name", "/path/to/dir"]
}
}

If a local server requires credentials (e.g., database passwords), it typically reads them from environment variables or config files rather than through the MCP authentication flow.

Credential Management#

Viewing Stored Credentials#

You can’t view the actual credential values, but you can see what’s stored:

> /debug

Shows credential scopes like:

Credentials:
source_oauth::workspace-id::github
source_bearer::workspace-id::exa

Removing Credentials#

To clear credentials for a specific source, delete its entry from the credentials file or remove the source entirely from Settings > Sources. To clear all credentials:

rm ~/.xiantong/credentials.enc

Credential Scoping#

Credentials are scoped hierarchically using a 3-part key format:

source_{authType}::{workspace_id}::{source_slug}

This means:

• Different workspaces have separate credentials
• Removing a source removes its credentials
• Credentials don’t leak between workspaces

Example: Multiple Auth Types#

A workspace with sources using different authentication methods:

[
{
"type": "mcp",
"name": "GitHub",
"tagline": "Repository and issue management",
"mcp": {
"transport": "http",
"url": "https://api.githubcopilot.com/mcp/",
"authType": "oauth"
}
},
{
"type": "mcp",
"name": "Exa Search",
"tagline": "Neural web search",
"mcp": {
"transport": "http",
"url": "https://mcp.exa.ai/mcp",
"authType": "bearer"
}
},
{
"type": "mcp",
"name": "Public API",
"tagline": "Public data access",
"mcp": {
"transport": "http",
"url": "https://public-api.example.com/mcp",
"authType": "none"
}
}
]

• GitHub - OAuth, opens browser for login
• Exa Search - Bearer, prompts for API key
• File System - Stdio, no network auth needed
• Public API - none, no auth required

Troubleshooting Authentication#

OAuth window doesn't open

• Check your default browser is working
• Ensure GUI access is available from the terminal
• Firewall may be blocking the local callback server

Token rejected by server

• Verify the token has required permissions/scopes
• Check if the token has expired
• Confirm the server URL is correct
• Ensure authType matches what the server expects

Re-authenticate after it was working

• Token may have been revoked
• Credentials file may have been corrupted
• Remove the source in Settings and re-add it to authenticate again

Wrong account authenticated

• Remove the source in Settings > Sources
• Re-add the source and authenticate with the correct account
• Check you’re logged into the right account in your browser

Security Best Practices#

Prefer OAuth over bearer tokens

OAuth tokens can be scoped, revoked, and rotated. Static tokens are harder to manage securely.

Use prompted token entry

Let xiantong prompt for tokens rather than storing them in configuration files.

Limit token scopes

When creating API keys or authorizing OAuth, grant only the permissions the source needs.

Rotate credentials periodically

For sensitive services, periodically clear and re-enter credentials to ensure they’re current.