MCP Servers

Returns a list of MCP servers registered to your chat model

GET /v1/mcp/servers

List MCP Servers

cURL

curl --request GET \
  --url https://us.inference.heroku.com/v1/mcp/servers \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "app_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "process_type": "<string>",
    "process_command": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "namespace": "<string>",
    "server_status": "registered",
    "primitives_status": "syncing",
    "tools": [
      {}
    ]
  }
]

The /v1/mcp/servers endpoint returns a list of MCP servers registered to your Heroku Managed Inference and Agents chat model. This list includes details about each server’s status, tools, and configuration.

View Working with MCP on Heroku to learn how to deploy and register custom MCP servers.

Base URL

https://us.inference.heroku.com

Authentication

All requests must include an Authorization header with your Heroku Inference API key:

Authorization: Bearer YOUR_INFERENCE_KEY

You can get your API key from your Heroku app’s INFERENCE_KEY config variable.

Request Parameters

This endpoint does not require any request parameters. It returns all MCP servers registered to your model.

Response

Returns an array of MCP Server objects, one per MCP server attached to your model.

MCP Server Object

id (string, uuid): Unique server ID

app_id (string, uuid): Heroku app ID where server is running

process_type (string): Process type used to start server, specified in the MCP app’s Procfile (must start with ‘mcp’)

process_command (string): Command used to run MCP STDIO server, specified in the Procfile

created_at (string, ISO 8601): Timestamp when server was registered

updated_at (string, ISO 8601): Timestamp when server was last updated

namespace (string): Name used to namespace tools served by this server

server_status (enum): Status of server. Options: registered, disconnected

primitives_status (enum): Status of the server’s tools list. Options: syncing, synced, error

tools (array): List of tools exposed by this server

Tool Object

Each server can expose multiple MCP tools.

name (string): Tool name that’s unique within its server namespace

namespaced_name (string): Fully-qualified tool name, formatted as namespace/tool_name

description (string, optional): Plain-text description for model grounding

input_schema (object): Input schema for tool call arguments, using JSON Schema

annotations (object): Optional hints about the tool’s functionality

Annotations fields:

• title (string, optional): UI-facing title for the tool
• readOnlyHint (boolean): True if tool has no side effects
• destructiveHint (boolean): True if the tool may delete or irreversibly modify data
• idempotentHint (boolean): True if calling multiple times has no marginal effect
• openWorldHint (boolean): True if the tool queries external or evolving real-world information

Example input schema:

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "The Ruby code to execute as a string."
    },
    "packages": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Optional list of gem names to install."
    }
  },
  "required": ["code"]
}

Examples

cURL

curl $INFERENCE_URL/v1/mcp/servers \
  -H "Authorization: Bearer $INFERENCE_KEY" \
  | jq

Response Example

[
  {
    "id": "a3bda372-085b-458f-8b1e-6f5704d528fe",
    "app_id": "434eb878-6bc1-4677-928d-80d27047ad5a",
    "process_type": "mcp",
    "process_command": "python -m src.stdio_server",
    "created_at": "2025-05-09T15:23:42.318541Z",
    "updated_at": "2025-05-09T15:23:45.890484Z",
    "namespace": "mcp",
    "server_status": "registered",
    "primitives_status": "synced",
    "tools": [
      {
        "name": "code_exec_ruby",
        "namespaced_name": "mcp/code_exec_ruby",
        "description": "Executes a Ruby code snippet with optional gem dependencies.",
        "input_schema": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "description": "The Ruby code to execute as a string."
            },
            "packages": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Optional list of gem names to install."
            },
            "use_temp_dir": {
              "type": "boolean",
              "default": false,
              "description": "If True, code runs in a temporary directory."
            }
          },
          "required": ["code"]
        },
        "annotations": {}
      }
    ]
  }
]

Important Notes

Only tools from servers with server_status: "registered" and primitives_status: "synced" will be accessible in /v1/agents/heroku requests.

• Use the /v1/agents/heroku endpoint to invoke tools registered by this endpoint
• Until you deploy and register an MCP server, requests will return an empty list
• MCP Tool and Server (Procfile process) names must be unique within a given add-on’s namespace
• Tool input schemas must follow the JSON Schema format

Related Endpoints

Agents (Heroku)

Invoke MCP tools with agents

Working with MCP

Deploy custom MCP servers

Heroku Tools

Built-in Heroku tools

Authorizations

Authorization · string · header · required

Bearer token using your INFERENCE_KEY

Response

200 - application/json

Successful response

id · string<uuid>

app_id · string<uuid>

process_type · string

process_command · string

created_at · string<date-time>

updated_at · string<date-time>

namespace · string

server_status · enum<string>

Available options: registered, disconnected

primitives_status · enum<string>

Available options: syncing, synced, error

tools · object[]