Talk to your agents

MCP Server

Copy page

Learn how to use the MCP server to talk to your agents

The MCP server allows you to talk to your agents through the Model Context Protocol.

Authentication

Choose the authentication method:

See Authentication → Run API for more details.

MCP Server Implementation

The MCP server is implemented in the @inkeep/agents-run-api library and provides a standard interface for agent communication.

Available Tools

The MCP server exposes one core tool:

send-query-to-agent

Sends a query to your agent graph's default agent. This tool:

  • Name: send-query-to-agent
  • Description: Dynamically generated based on your agent graph's name and description
  • Parameters:
    • query (string): The query to send to the agent
  • Returns: The agent's response as text content

Example usage in Cursor: When the MCP server is configured, Cursor will automatically discover this tool and you can use it by asking questions. The tool will route your query to the appropriate agent in your graph and return the response.

The tool handles:

  • Message creation and conversation management
  • Agent execution with your configured tools and capabilities
  • Context resolution if your graph has context configuration
  • Error handling and response formatting

Using with Cursor

Add the following configuration to your Cursor MCP settings.

Example

Example when using an API key for auth:

{
  "AgentName": {
    "type": "mcp",
    "url": "http://<your-run-api-url>/v1/mcp",
    "headers": {
      "Authorization": "Bearer <graph_api_key>"
    }
  }
}

Session Management (Required by MCP HTTP Transport)

  • Initialize a session by sending an initialize JSON-RPC request to /v1/mcp.
  • The server will respond and set Mcp-Session-Id in response headers.
  • For all subsequent JSON-RPC requests in that session, include Mcp-Session-Id header with the value from initialization.
Note
Note

Session management is required by MCP’s HTTP transport. If Mcp-Session-Id is missing or invalid on follow-up requests, the server will return a JSON-RPC error (e.g., "Session not found").

Configuration Notes

  • URL: Point to your agents-run-api instance (default: http://localhost:3003)
  • Headers: Use the appropriate authentication mode per the section above
  • Authorization: Only required outside development mode