Authentication & Security

Learn about MCP authentication methods, required headers, and security best practices for StackOne MCP integration.

Authentication Methods

StackOne MCP server uses the same authentication as the regular StackOne API, ensuring consistent security across all integration methods.

Get your API key

1. Go to Configuration → API Keys in the dashboard
2. Click Create API Key and copy it securely

API keys are shown only once. Store securely.

See API Keys Guide for detailed instructions.

Get your Account ID

1. Go to Accounts in the dashboard
2. Select your linked account
3. Copy the account ID (e.g., 47187425466113776871)

You can also retrieve account IDs via the List Accounts API.

Basic Authentication (Recommended)

StackOne MCP uses the same Basic Auth as all StackOne APIs:

cURL

# -u flag auto-encodes to base64
curl -u "$STACKONE_API_KEY:" https://api.stackone.com/mcp ...

TypeScript

const encoded = Buffer.from(`${apiKey}:`).toString('base64');
fetch(url, { headers: { 'Authorization': `Basic ${encoded}` } });

Python

import base64
encoded = base64.b64encode(f"{api_key}:".encode()).decode()
headers = {'Authorization': f'Basic {encoded}'}

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

Critical: Accept Header is Mandatory

The Accept: application/json,text/event-stream header is required by the MCP specification (version 2025-03-26), not just StackOne.

• Both formats must be listed - you cannot use only application/json or wildcards like */*
• This header is required on every request (initialize, tools/list, tools/call, etc.)
• Without this header, you’ll receive a 406 Not Acceptable error

This requirement allows the MCP server to choose between returning single JSON responses or Server-Sent Events streams based on the operation.

Source: MCP Specification - Streamable HTTP Transport

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:

1. Header Method (Recommended)

x-account-id: 47187425466113776871

2. Query Parameter (Fallback)

For clients that don’t support custom headers:

https://api.stackone.com/mcp?x-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 (especially Accept header)
• Base64 encoding problems
• Account ID validation
• 406 Not Acceptable errors

Testing Authentication

Verify your authentication setup with a simple initialize CURL request or using Postman:

cURL

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