ClosedMCP
Browse guides · API reference

API reference

Choose what you want to build. Each example shows the token and request you need.

Choose an API task

Make your first tool call

1. Sign in a user

First, register your app and sign in a user. Copy the access token from the response.

Register your app and sign in a user

2. Start a session

Replace the token with the access token from sign-in. Run this whole example to start and confirm a session. It saves the session ID for the next steps.

Start and confirm a session
BASE=https://closedmcp.com
TOKEN='<access_token>'
curl -sS -D /tmp/closedmcp-headers "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize",
    "params":{"protocolVersion":"2025-11-25",
      "capabilities":{},
      "clientInfo":{"name":"My app","version":"1"}}}'
SESSION=$(awk 'tolower($1) == "mcp-session-id:" {
  gsub(/\r/, "", $2); print $2
}' /tmp/closedmcp-headers)
curl -sS "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
Session response and help

The initialize response header contains Mcp-Session-Id. If your app is waiting for approval, an admin must allow it in Clients before it can use tools. The initialize response includes its approval status in instructions.

Initialize response · excerpt
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "tools": { "listChanged": true }, "logging": {} },
    "serverInfo": { "name": "closedmcp", "version": "0.1.0" }
  }
}

3. List available tools

Run the session setup above first; this command uses its saved values.

List available tools
curl "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list",
    "params":{}}'

4. Call a tool

Run the session setup above first; this command uses its saved values.

Call a tool
curl "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,
    "method":"tools/call","params":{
      "name":"closedmcp_list_servers",
      "arguments":{}}}'
About this example

This calls the built-in tool that checks installed servers. To call another tool, use its name and argument schema from the list response.

Endpoint reference

List available tools

POST/mcp · tools/list

Lists the tools available to this person. Send the access token in the Authorization header.

Authentication: Bearer access token.

Copy request

Run the session setup above first; this command uses its saved values.

Terminal
curl "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list",
    "params":{}}'
View response
Successful response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "closedmcp_list_servers",
        "description": "Availability and health.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "env": {
              "type": "string"
            }
          }
        }
      }
    ]
  }
}
Notes and errors

Excerpt. The result also includes other built-in tools and tools allowed for this person.

Errors: HTTP 401: invalid or expired token. HTTP 403: company mismatch.

Call a tool

POST/mcp · tools/call

Calls a tool by its name with arguments that match its schema.

Authentication: Bearer access token. The AI app must be allowed.

Copy request

Run the session setup above first; this command uses its saved values.

Terminal
curl "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,
    "method":"tools/call","params":{
      "name":"closedmcp_list_servers",
      "arguments":{}}}'
View response
Successful response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[]"
      }
    ]
  }
}
Notes and errors

Example for a workspace with no installed servers. Text contains a JSON array of server details when tools are installed.

Errors: JSON-RPC -32001: missing identity or blocked AI app. -32602: invalid tool call. Tool failures may return result.isError: true.

Watch for tool changes

GET/mcp

Keep a stream open to hear when your available tools change. Needs a bearer token.

Authentication: Bearer access token.

Copy request

Run the session setup above first; this command uses its saved values.

Terminal
curl -N "$BASE/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -H 'Accept: text/event-stream'
View response
Successful response
event: message
data: {"jsonrpc":"2.0","method":"notifications/tools/list_changed"}
Notes and errors

Event data is sent on one line. List tools again after a change.

Errors: HTTP 401: invalid or expired token. HTTP 429: too many open streams.