MCP Endpoint
apistash implements the Model Context Protocol (MCP) using the Streamable HTTP transport.
Endpoint
POST https://api.apistash.io/mcp
Transport
| Property | Value |
|---|---|
| Protocol | MCP Streamable HTTP |
| Method | POST for requests and notifications; GET opens the server-to-client event stream; DELETE ends the session |
| Content-Type | application/json on POST |
| Accept | application/json, text/event-stream on POST; text/event-stream on GET |
| Auth header | X-API-Key: <api-key> for an API key, or Authorization: Bearer <OAuth token> for OAuth (required) |
Your client handles all three automatically — you only ever configure the URL. GET and DELETE carry the session id your client received when it connected, and no body.
What it exposes
The MCP endpoint advertises three native protocol capabilities, each with change notifications:
- Tools — discover with
tools/list, invoke withtools/call. Includes the built-in tools and your custom tools. - Prompts — discover with
prompts/list, fetch withprompts/get. - Resources — discover with
resources/list, read withresources/read, and watch withresources/subscribe.
All three lists are computed per credential — you see only what you are allowed to reach (see the access model). The server sends *_list_changed notifications when a credential's visible list can change.
agent definitions use an independent fourth access category,
Agents (agents for API keys, mcp_agents for OAuth), but are delivered through the authenticated
system tools bootstrap and agent_context rather than a fourth protocol capability or list.
Agent selection or content still requires Agents and current Agent visibility.
Tool input schemas follow JSON Schema.
Authentication
The MCP endpoint requires authentication — send an API key in the X-API-Key header, or an OAuth token in the Authorization: Bearer header. Your credential reaches the built-in tools plus your custom tools, prompts, and resources, each filtered to what it is allowed to see. bootstrap requires an explicit primary_agent declaration and returns task-specific Agent behavior separately from visible Agent discovery. OAuth-capable clients use the discovery metadata below after the client has been registered in the dashboard; apistash does not dynamically register an unknown client.
Each HTTP request is authenticated, including requests within an existing MCP session. OAuth access tokens stop being accepted at their signed expiry time, with no grace period. Refresh the token through your client's OAuth flow before sending the next request; a session id does not extend the token's lifetime.
Dashboard session cookies and JWTs are not accepted on the MCP endpoint. See Authentication.
Protocol version
apistash negotiates the MCP protocol version with your client during the initialize handshake. A
spec-compliant client must also support the Streamable HTTP transport to connect to this endpoint.
OAuth discovery
For clients that authenticate with OAuth, apistash publishes discovery metadata so the registered client can locate the authorization endpoints:
https://api.apistash.io/.well-known/oauth-protected-resource/mcp— points from the MCP endpoint to its authorization server (RFC 9728)https://api.apistash.io/.well-known/oauth-authorization-server— authorization-server metadata (RFC 8414)
Discovery locates the endpoints; it does not create a client registration. See Authentication → OAuth.
Connecting
See MCP Clients for step-by-step connection instructions and Set up task-start context for native persistent instruction scopes.