> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<AccordionGroup>
  <Accordion title="Get your API key" icon="key">
    1. Go to <a href="https://app.stackone.com/api_keys" target="_blank">**Configuration → API Keys**</a> in the dashboard
    2. Click **Create API Key** and copy it securely

    <Warning>
      API keys are shown only once. Store securely.
    </Warning>

    See [API Keys Guide](/guides/api-keys) for detailed instructions.
  </Accordion>

  <Accordion title="Get your Account ID" icon="id-card">
    1. Go to <a href="https://app.stackone.com/accounts" target="_blank">**Accounts**</a> 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](/platform/api-reference/accounts/list-accounts).
  </Accordion>
</AccordionGroup>

### Basic Authentication (Recommended)

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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # -u flag auto-encodes to base64
    curl -u "$STACKONE_API_KEY:" https://api.stackone.com/mcp ...
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const encoded = Buffer.from(`${apiKey}:`).toString('base64');
    fetch(url, { headers: { 'Authorization': `Basic ${encoded}` } });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import base64
    encoded = base64.b64encode(f"{api_key}:".encode()).decode()
    headers = {'Authorization': f'Basic {encoded}'}
    ```
  </Tab>
</Tabs>

## Required Headers

### Core Headers

All MCP requests require these headers:

```bash theme={null}
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
Content-Type: application/json
Accept: application/json,text/event-stream
```

<Warning>
  **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](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)
</Warning>

**Optional Protocol Header:**

```bash theme={null}
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)

```bash theme={null}
x-account-id: 47187425466113776871
```

### 2. Query Parameter (Fallback)

For clients that don't support custom headers:

```bash theme={null}
https://api.stackone.com/mcp?x-account-id=47187425466113776871
```

**Account ID Format:**

* Numeric string (e.g., `47187425466113776871`)
* Short alphanumeric ID (e.g., `abc123xyz`)

<Note>
  The header method takes precedence if both are provided. Use query parameters only when custom headers are not supported by your MCP client.
</Note>

## 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](/mcp/troubleshooting) 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](/mcp/quickstart#postman-testing-visual-interface):

<CodeGroup>
  ```bash cURL theme={null}
  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": {}
      }
    }'
  ```
</CodeGroup>

A successful response confirms your authentication is configured correctly.

## Next Steps

Once authentication is configured:

<CardGroup cols={2}>
  <Card title="Try the Quickstart" icon="rocket" href="/mcp/quickstart">
    Test your setup with basic MCP operations
  </Card>

  <Card title="Choose Your Client" icon="desktop" href="/mcp/app-guides/claude-desktop">
    Configure your preferred MCP client
  </Card>
</CardGroup>