MCP Authentication - Craft Agents

MCP servers often require authentication to access their tools. Craft Agents 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:

Type	Use Case	How It Works
oauth	Interactive login, user-scoped access	Opens browser for authorization
bearer	Static tokens, API keys	Prompts for token entry
none	No authentication needed	No configuration required

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:

Craft Agents detects OAuth authentication is required
A browser window opens for you to authorize access
After approval, you’re redirected back to the application
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 ~/.craft-agent/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 ~/.craft-agent/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 Craft Agents 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.

​Authentication Types

​OAuth Authentication

​Token Refresh

​Bearer Token Authentication

​Public Servers

​Local Servers (Stdio)

​Credential Management

​Viewing Stored Credentials

​Removing Credentials

​Credential Scoping

​Example: Multiple Auth Types

​Troubleshooting Authentication

​Security Best Practices