Skip to main content

​
Overview

StackOne provides a Model Context Protocol (MCP) server for each linked account at: 
https://api.stackone.com/mcp
Authentication: All requests require Basic authentication (Authorization header with base64-encoded API key) and your StackOne account ID (x-account-id header or ?account_id= query parameter). This guide walks you through the basic MCP operations to help you understand the protocol before integrating with your preferred client or framework.
For clients that don’t support the x-account-id custom header, you can use a query parameter instead: ?account_id=<ACCOUNT_ID>

​
Quick Testing Options

Choose your preferred testing method to get started with StackOne’s MCP server:

​
Programmatic Testing

Perfect for developers who prefer command-line tools or want to integrate MCP into scripts.

​
Step 1: Initialize Connection

The initialize method starts an MCP session and negotiates capabilities:
curl -X POST https://api.stackone.com/mcp \
  -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
  -H 'x-account-id: <ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json,text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      },
      "protocolVersion": "2025-06-18",
      "capabilities": {}
    }
  }'
Expected Response:
{
  "jsonrpc": "2.0",
  "id": "init-1",
  "result": {
    "serverInfo": {
      "name": "stackone-mcp-server",
      "version": "1.0.0"
    },
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "logging": {}
    }
  }
}

​
Step 2: List Available Tools

Use tools/list to discover all available StackOne operations:
curl -X POST https://api.stackone.com/mcp \
  -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
  -H 'x-account-id: <ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json,text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-1",
    "method": "tools/list"
  }'
Example Response with Tool(s) Available:
{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "result": {
    "tools": [
      {
        "name": "ashby_list_applications",
        "description": "List applications from Ashby",
        "inputSchema": {
          "type": "object",
          "properties": {
            "limit": {
              "type": "number"
            }
          }
        }
      }
    ]
  }
}

​
Step 3: Execute a Tool

Call tools/call to execute any StackOne operation:
curl -X POST https://api.stackone.com/mcp \
  -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
  -H 'x-account-id: <ACCOUNT_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json,text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": "call-1",
    "method": "tools/call",
    "params": {
      "name": "ashby_list_applications",
      "arguments": {
        "limit": 10
      }
    }
  }'
Expected Response:
{
  "jsonrpc": "2.0",
  "id": "call-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"data\": [\n    {\n      \"id\": \"emp_123\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@company.com\",\n      \"employment_status\": \"active\"\n    }\n  ],\n  \"pagination\": {\n    \"next_cursor\": \"abc123\"\n  }\n}"
        }
    ]
  }
}

​
GUI-Based Testing

Perfect for teams that prefer visual interfaces and want to share API collections.

​
Video Walkthrough

​
Setup Instructions

  1. Download Postman: Get Postman from postman.com
  2. Create a New Collection: Name it “StackOne MCP Testing”
  3. Set Up Environment Variables:
    • Click “Environments” → “Create Environment” (you can use one environment per StackOne project to make it easier to handle multiple projects)
    • Add variable:
      • api_key = Your StackOne API key
  4. Create MCP Request
    • Set-up protocol to HTTP not STDIO
    • The server url should be https://api.stackone.com/mcp
    • For Authorization, select Basic Auth and set username to your {{api_key}} environment variable
    • Go to headers and add x-account-id header with the StackOne account ID you want to use
Postman automatically handles Base64 encoding for Basic Auth - no manual encoding needed!

​
Using the Server

  1. Click the connect button on the right hand-side. This will do the initial connection with the MCP server and list all available tools
    • If successful, the response section will say connected
  2. Go to the Message tab on the left of Authorization
  3. You will see the list of Tools associated with the StackOne Account ID
  4. Click on any of the tools and try/test them out!

​
Pro Tips

  • Save Requests: Save each request in your collection for reuse and easy sharing with your team.
  • Use the Tests Tab: Add validation scripts in Postman’s Tests tab to automatically verify responses.
  • Share Collections: Export and share collections with teammates to standardize testing.
  • Try Other Tools: Use the tools listed in Step 2’s response to experiment with different operations.

​
Next Steps

Now that you understand the basic MCP operations, choose your integration path:

Connect a Client

Set up Claude, ChatGPT, Cursor, or other LLM clients

Use an SDK

Integrate programmatically with Python or TypeScript

​
Common Issues & Solutions

1

Verify your API key is correctly base64 encoded
2

Confirm that the x-account-id header matches your linked account ID, and ensure the account belongs to the same project as your API key.
1

Ensure you’re using POST requests
2

Verify the correct Content-Type: application/json header
3

Check that the endpoint URL and payload is correct
1

Check that the account is active (ie. is not in an error state or otherwise disabled)
2

Verify your integrations are properly configured (MCP tools are generated based on the enabled actions for the integration configuration associated with the linked account)
For more troubleshooting, see our Troubleshooting Guide.