MCP Clients

apistash uses the MCP Streamable HTTP transport. Any client that supports that transport can connect.

Dashboard JWTs are not accepted

The MCP endpoint only accepts API keys and OAuth tokens. Dashboard session cookies and JWTs (the credentials your browser uses when you are signed in) are not valid on this endpoint and return 403 mcp_access_denied.

Generate an API key from the dashboard and use it in a client that accepts custom request headers, or register an OAuth client for clients such as Claude Desktop that connect through OAuth.

Pick your client below and follow its native configuration. Except where noted for Claude Desktop, the examples send an API key in the X-API-Key header. Get an API key → and create it with the Tools capability selected for ordinary tools — a key with no capabilities still reaches the authenticated system tools, but no governed native surface or agent definition. OAuth requires a client registration created in the dashboard; discovery tells the client where to authorize, but apistash does not dynamically register unknown clients. See Authentication.

Select your tools first

A credential reaches the governed tools you selected under Settings → MCP Settings in the dashboard — that selection is what keeps your agent's context small. The system tools setup, bootstrap, and agent_context are always present and are not part of this selection. See Quick Start.

---

Supported clients

Claude Desktop

Claude Desktop connects to a remote MCP server through a custom connector, not through claude_desktop_config.json. That file is for local MCP servers and Claude Desktop does not load a remote server configured there.

Claude's remote connector does not accept an arbitrary X-API-Key header, so use OAuth:

1. In the apistash dashboard, register a confidential OAuth client with the authorization-code grant, https://claude.ai/api/mcp/auth_callback as its redirect URI, and tool access among its scopes. Copy the client ID and one-time client secret.
2. In Claude Desktop, open Customize → Connectors, choose Add custom connector, and enter https://api.apistash.io/mcp.
3. Open Advanced settings, enter the registered client ID and secret, then add the connector.
4. Choose Connect and complete the apistash authorization flow. Enable the connector for the conversation from the + → Connectors menu.

For Team and Enterprise Claude accounts, an Owner must first add the custom connector under the organization's connector settings. Members then connect their own authorization.

Cursor

Config file locations:

• Global: ~/.cursor/mcp.json
• Project-specific: .cursor/mcp.json (in your project root)

{
	"mcpServers": {
		"apistash": {
			"url": "https://api.apistash.io/mcp",
			"headers": {
				"X-API-Key": "YOUR_API_KEY"
			}
		}
	}
}

Alternatively, open Customize → MCP and add the same remote server there. After saving, use that page to verify that apistash is connected and exposes the expected tools.

Windsurf (Cascade)

This configuration applies to the legacy Cascade agent in Devin Desktop (formerly Windsurf). New tabs use Devin Local by default, whose MCP configuration is separate. Use the following file or settings page only when you are working in Cascade.

Config file: ~/.codeium/windsurf/mcp_config.json (same path on macOS, Linux, and Windows)

Windsurf names the endpoint field serverUrl rather than url — that is its own schema, so keep it as shown:

{
	"mcpServers": {
		"apistash": {
			"serverUrl": "https://api.apistash.io/mcp",
			"headers": {
				"X-API-Key": "YOUR_API_KEY"
			}
		}
	}
}

You can also open Devin Settings → Cascade → MCP Servers and add the server there.

After saving, click Refresh in the MCP Servers panel so Cascade reloads the server list.

Keep the key out of the file

Windsurf interpolates ${env:VAR_NAME} inside headers, so you can write "X-API-Key": "${env:APISTASH_API_KEY}" and keep the key in your environment instead of the config file.

OpenCode

Config file: opencode.jsonc (project root or ~/.config/opencode/opencode.jsonc for global)

{
	"$schema": "https://opencode.ai/config.json",
	"mcp": {
		"servers": {
			"apistash": {
				"type": "remote",
				"url": "https://api.apistash.io/mcp",
				"oauth": false,
				"headers": {
					"X-API-Key": "YOUR_API_KEY"
				}
			}
		}
	}
}

OpenCode V2 places named servers under mcp.servers; the older shape with apistash directly under mcp is not valid V2 configuration. After saving, use OpenCode's MCP management interface to verify the configured server and its connection status.

Cline

Cline stores MCP settings in cline_mcp_settings.json. Open Cline's panel, click the MCP Servers icon, select the Configure tab, then click Configure MCP Servers.

{
	"mcpServers": {
		"apistash": {
			"type": "streamableHttp",
			"url": "https://api.apistash.io/mcp",
			"headers": {
				"X-API-Key": "YOUR_API_KEY"
			},
			"disabled": false
		}
	}
}

Save the file — Cline connects immediately without a restart.

Continue

Create a YAML file at .continue/mcpServers/apistash.yaml inside your project (or add the same mcpServers entry to ~/.continue/config.yaml for global scope). Standalone block files require the top-level metadata shown here:

name: apistash MCP
version: 1.0.0
schema: v1
mcpServers:
  - name: apistash
    type: streamable-http
    url: https://api.apistash.io/mcp
    requestOptions:
      headers:
        X-API-Key: 'YOUR_API_KEY'

Reload the Continue extension after saving (Ctrl/Cmd + Shift + P → Continue: Reload config).

Gemini CLI

Config file: ~/.gemini/settings.json

{
	"mcpServers": {
		"apistash": {
			"url": "https://api.apistash.io/mcp",
			"type": "http",
			"headers": {
				"X-API-Key": "YOUR_API_KEY"
			}
		}
	}
}

Or use the CLI to add the server in one command:

gemini mcp add --transport http \
  --header "X-API-Key: YOUR_API_KEY" \
  apistash https://api.apistash.io/mcp

Verify the connection with /mcp inside the Gemini CLI session.

Custom agent (SDK)

Use the official MCP TypeScript SDK to connect directly from your own agent or script.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://api.apistash.io/mcp'), {
	requestInit: {
		headers: {
			'X-API-Key': 'YOUR_API_KEY'
		}
	}
});

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools);

Install the SDK with:

npm install @modelcontextprotocol/sdk

---

Connection reference

Property	Value
Transport	StreamableHTTP
Endpoint	https://api.apistash.io/mcp
Method	POST
Auth header	X-API-Key: <api-key> for an API key, or Authorization: Bearer <OAuth token> for OAuth (required)
Content-Type	application/json
Accept	application/json, text/event-stream

info

If your client only supports the older SSE transport, let us know — we may add backwards-compatibility support.

OAuth

apistash publishes standard discovery metadata, but the client itself must be registered in the dashboard before it can authorize. See Authentication → OAuth.

---

Verify your connection

After configuring your client, ask it to list the available tools. In most clients you can type something like:

"What tools do you have available from apistash?"

The model should respond with the tools you selected plus the three system tools. If a selected tool is missing, check Settings → MCP Settings — see Troubleshooting.

If you want optional persistent task-start setup after verifying the connection, explicitly ask your agent exactly:

"Set up apistash."

General setup also offers an optional conversation to propose useful Agents, Prompts, and Resources. The agent checks existing content and shows concrete drafts and ownership targets for confirmation before governed writes. You can decline; repair-only requests do not start the interview.

It calls setup and uses the current client's own persistent-instruction mechanism; the apistash server and dashboard do not write local client files. The setup call is not automatic, and a client with no writable instruction target must show the canonical instruction and report not_installed. See Set up task-start context for the current native target and scope for each client. setup, bootstrap, and agent_context are always available to an authenticated credential. Agent selection and content still require Agents / mcp_agents and the applicable Agent visibility controls.