Skip to main content

​
Authentication Methods

StackOne MCP server uses the same authentication as the regular StackOne API, ensuring consistent security across all integration methods.
Get API Key:
  1. Log into StackOne Dashboard
  2. Navigate to your project
  3. Go to Settings → API Keys
  4. Create or copy existing API key
Get Account ID:
  1. Go to Accounts section in dashboard
  2. Select your linked account
  3. Copy the account ID (numeric format like 47187425466113776871 or short alphanumeric ID)
You can also retrieve account IDs programmatically via the List Accounts API endpoint.See API Keys Guide for detailed instructions.
The primary authentication method uses HTTP Basic Auth with your StackOne API key: 
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
How to create the Basic Auth token:
  1. Take your StackOne API key (e.g., v1.us1.AAblXDxi8h_OO1AZG_Hyg4V3w65x9...)
  2. Append a colon: v1.us1.YYplXCxi8h_OO9HZG_Kyg4V3w65x9...:
  3. Base64 encode the result
echo -n "<stackone_api_key>:" | base64

​
Required Headers

​
Core Headers

All MCP requests require these headers: 
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
Content-Type: application/json
Accept: application/json,text/event-stream
Optional Protocol Header: 
MCP-Protocol-Version: 2025-06-18
StackOne supports protocol versions 2025-03-26 and 2025-06-18. Most clients handle this automatically.

​
Account ID

The account ID can be passed in two ways: 
x-account-id: 47187425466113776871

​
2. Query Parameter (Fallback)

For clients that don’t support custom headers: 
https://api.stackone.com/mcp?account_id=47187425466113776871
Account ID Format:
  • Numeric string (e.g., 47187425466113776871)
  • Short alphanumeric ID (e.g., abc123xyz)
The header method takes precedence if both are provided. Use query parameters only when custom headers are not supported by your MCP client.

​
Transport Protocol

StackOne uses Streamable HTTP transport exclusively:
  • Protocol: HTTPS only
  • Method: POST requests for all operations
  • No SSE: Server-Sent Events are not supported
  • Session Management: Stateless (no session support currently)

​
Security Best Practices

​
Always Use HTTPS

✅ Correct: https://api.stackone.com/mcp ❌ Incorrect: http://api.stackone.com/mcp

​
Store API Keys Securely

Use environment variables and never commit API keys to version control.

​
Troubleshooting Authentication

For authentication errors and common issues, see our comprehensive Troubleshooting Guide which covers:
  • 401 Unauthorized errors
  • 403 Forbidden errors
  • Missing header issues
  • Base64 encoding problems
  • Account ID validation

​
Testing Authentication

Verify your authentication setup with a simple initialize CURL request or using Postman: 
curl -X POST https://api.stackone.com/mcp \
  -H 'Authorization: Basic <YOUR_BASE64_TOKEN>' \
  -H 'x-account-id: <YOUR_ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json,text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "id": "auth-test",
    "method": "initialize",
    "params": {
      "clientInfo": {"name": "auth-test", "version": "1.0.0"},
      "protocolVersion": "2025-06-18",
      "capabilities": {}
    }
  }'
A successful response confirms your authentication is configured correctly.

​
Next Steps

Once authentication is configured:

Try the Quickstart

Test your setup with basic MCP operations

Choose Your Client

Configure your preferred MCP client