Documentation Index
Fetch the complete documentation index at: https://docs.getmcp.com/llms.txt
Use this file to discover all available pages before exploring further.
GetMCP authentication has two separate layers. Confusing them is the most common source of auth errors.
| Layer 1 | Layer 2 |
|---|
| What it protects | Access to your MCP server | The external API your tool calls |
| Who configures it | Server owner | Server owner (fixed key) or end user (own key) |
| Where it goes | MCP client config — --header args (Claude Desktop) or headers object (others) | Tool’s Custom Headers or MCP client headers |
Layer 1 — Who Can Connect to Your Server
Every GetMCP server has a unique URL:
https://yoursite.com/mcp/{server-slug}
Treat your server URL like a password. Don’t post it publicly or commit it to source code. If compromised, regenerate it in Server Settings.
| Auth Type | Client must send |
|---|
none | Nothing (URL alone grants access) |
bearer-token | Authorization: Bearer <token> |
api-key | Authorization: <api-key> or ?keyName=value in the URL |
basic-auth | HTTP Basic credentials (Authorization: Basic <base64>) |
oauth | Browser-based OAuth flow (no static credential) |
Claude Desktop
Claude Code
Cursor
Windsurf
VS Code
Pass the credential as a --header arg (no space after the colon):Bearer token:{
"mcpServers": {
"my-server": {
"command": "npx",
"args": [
"mcp-remote",
"https://yoursite.com/mcp/my-server",
"--header",
"Authorization:Bearer YOUR_BEARER_TOKEN"
]
}
}
}
username:password first):{
"mcpServers": {
"my-server": {
"command": "npx",
"args": [
"mcp-remote",
"https://yoursite.com/mcp/my-server",
"--header",
"Authorization:Basic BASE64_USERNAME_PASSWORD"
]
}
}
}
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": [
"mcp-remote",
"https://yoursite.com/mcp/my-server",
"--header",
"X-API-Key:YOUR_API_KEY"
]
}
}
}
--header needed. For query-param keys, append ?keyName=YOUR_KEY to the URL. OAuth opens a browser flow automatically.On Windows, replace "command": "npx" with "command": "cmd" and add "/c" and "npx" as the first two args before "mcp-remote". Bearer token:claude mcp add --transport http my-server https://yoursite.com/mcp/my-server \
--header "Authorization: Bearer YOUR_BEARER_TOKEN"
username:password first):claude mcp add --transport http my-server https://yoursite.com/mcp/my-server \
--header "Authorization: Basic BASE64_USERNAME_PASSWORD"
claude mcp add --transport http my-server https://yoursite.com/mcp/my-server \
--header "X-API-Key: YOUR_API_KEY"
--header needed. For query-param keys, append ?keyName=YOUR_KEY to the URL.claude mcp add --transport http my-server https://yoursite.com/mcp/my-server
Add a headers object before url in mcp.json:Bearer token:{
"mcpServers": {
"my-server": {
"headers": {
"Authorization": "Bearer YOUR_BEARER_TOKEN"
},
"url": "https://yoursite.com/mcp/my-server"
}
}
}
username:password first):{
"mcpServers": {
"my-server": {
"headers": {
"Authorization": "Basic BASE64_USERNAME_PASSWORD"
},
"url": "https://yoursite.com/mcp/my-server"
}
}
}
{
"mcpServers": {
"my-server": {
"headers": {
"X-API-Key": "YOUR_API_KEY"
},
"url": "https://yoursite.com/mcp/my-server"
}
}
}
headers needed — use the plain URL. For query-param keys, append ?keyName=YOUR_KEY to the URL.{
"mcpServers": {
"my-server": {
"url": "https://yoursite.com/mcp/my-server"
}
}
}
Add a headers object before serverUrl in mcp_config.json:Bearer token:{
"mcpServers": {
"my-server": {
"headers": {
"Authorization": "Bearer YOUR_BEARER_TOKEN"
},
"serverUrl": "https://yoursite.com/mcp/my-server"
}
}
}
username:password first):{
"mcpServers": {
"my-server": {
"headers": {
"Authorization": "Basic BASE64_USERNAME_PASSWORD"
},
"serverUrl": "https://yoursite.com/mcp/my-server"
}
}
}
{
"mcpServers": {
"my-server": {
"headers": {
"X-API-Key": "YOUR_API_KEY"
},
"serverUrl": "https://yoursite.com/mcp/my-server"
}
}
}
headers needed — use the plain URL. For query-param keys, append ?keyName=YOUR_KEY to the URL.{
"mcpServers": {
"my-server": {
"serverUrl": "https://yoursite.com/mcp/my-server"
}
}
}
VS Code’s ${input:} syntax prompts you to enter the value securely on first use:Bearer token:{
"servers": {
"my-server": {
"type": "http",
"url": "https://yoursite.com/mcp/my-server",
"headers": {
"Authorization": "Bearer ${input:my-server-key}"
}
}
}
}
{
"servers": {
"my-server": {
"type": "http",
"url": "https://yoursite.com/mcp/my-server",
"headers": {
"Authorization": "Basic ${input:my-server-key}"
}
}
}
}
{
"servers": {
"my-server": {
"type": "http",
"url": "https://yoursite.com/mcp/my-server",
"headers": {
"X-API-Key": "${input:my-server-key}"
}
}
}
}
headers needed — use the plain URL. For query-param keys, append ?keyName=YOUR_KEY to the URL.{
"servers": {
"my-server": {
"type": "http",
"url": "https://yoursite.com/mcp/my-server"
}
}
}
When a tool runs, GetMCP calls an external API. That API usually requires credentials. There are two ways to supply them:
Fixed credentials — all users share the same key
Add the key as a Custom Header in the tool’s Advanced Settings:
| Header name | Header value |
|---|
Authorization | Bearer sk_your_token |
X-API-Key | your_api_key |
https://api.example.com/data?api_key=your_key
Each tool has its own Custom Headers, so different tools can call different APIs with different credentials.
User-supplied credentials — each user brings their own key
When each user has their own account on the external service (e.g., their own OpenAI key), they pass their key through their own MCP client config:
Claude Desktop
Claude Code
Cursor
Windsurf
VS Code
Pass the key as a --header arg to mcp-remote (no space after the colon):{
"mcpServers": {
"my-server": {
"command": "npx",
"args": [
"mcp-remote",
"https://yoursite.com/mcp/my-server",
"--header",
"Authorization:Bearer sk-their-own-openai-key"
]
}
}
}
"command": "npx" with "command": "cmd" and add "/c" and "npx" as the first two args before "mcp-remote". claude mcp add --transport http my-server https://yoursite.com/mcp/my-server \
--header "Authorization: Bearer sk-their-own-openai-key"
{
"mcpServers": {
"my-server": {
"headers": {
"Authorization": "Bearer sk-their-own-openai-key"
},
"url": "https://yoursite.com/mcp/my-server"
}
}
}
{
"mcpServers": {
"my-server": {
"headers": {
"Authorization": "Bearer sk-their-own-openai-key"
},
"serverUrl": "https://yoursite.com/mcp/my-server"
}
}
}
VS Code’s ${input:} syntax prompts you to enter the value securely on first use:{
"servers": {
"my-server": {
"type": "http",
"url": "https://yoursite.com/mcp/my-server",
"headers": {
"Authorization": "Bearer ${input:my-server-key}"
}
}
}
}
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
For other clients, see Connecting AI Clients.
Test Credentials
When you click Test on a tool in the admin, GetMCP uses test credentials — not the production keys in Custom Headers.
Configure test credentials in the server detail page → Authentication tab → Test Credentials section. All tools in the server share the same test credentials, keeping your production keys safe during development.
Test credentials are only used when you click Test in the admin panel. AI client calls always use the tool’s Custom Headers — never test credentials.
Troubleshooting
Tool returns 401 Unauthorized
→ The API key is missing or wrong. For user-supplied keys, check the auth config in your MCP client (for Claude Desktop, --header args; for others, the headers block). For fixed keys, check the tool’s Custom Headers in the admin.
Tool returns 403 Forbidden
→ The key is valid but lacks permissions. Check the scopes or roles for that key in the external service’s dashboard.
Server connects but tools fail with auth errors
→ You may be confusing Layer 1 and Layer 2. The headers you add to connect to GetMCP (Layer 1) are separate from the API credentials the tool uses to call an external service (Layer 2). You may need to configure both.
Don’t know where your config file is
→ See Connecting AI Clients for file paths per client.
