Skip to content

MCP Integration

Model Context Protocol (MCP) allows Gravity to connect to external tool servers. MCP agents appear alongside built-in agents and can be invoked by the LLM during task execution.

Configuration

Configure MCP servers in settings.json under McpServers:

{
  "McpServers": {
    "filesystem": {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\workspace"]
    },
    "github": {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}
FieldTypeDescription
namestringUnique server identifier
commandstringExecutable to spawn (e.g., npx, python, uvx)
argsstring[]Command arguments
envobjectEnvironment variables for the process

JSON-RPC Protocol

MCP agents communicate via stdio JSON-RPC 2.0. The McpClient handles:

  • Process spawning and lifecycle management
  • Message framing (newline-delimited JSON)
  • Request/response correlation via IDs
  • Capability negotiation on initialization
  • Tool/list_resources/list_prompts discovery
  • Automatic reconnection on crash

McpAgent Wrapper

The McpAgent wraps an MCP server as an IAgent:

  • Exposes MCP tools through standard AgentDescriptor
  • Routes calls via ReasoningRouter (same as built-in agents)
  • Handles parameter validation and approval policies
  • Supports both tools and resources

MCP tools appear in the LLM's tool manifest with namespaced names like mcp_filesystem.read_file.

Example: Filesystem Server

Install the official MCP filesystem server:

npm install -g @modelcontextprotocol/server-filesystem

Add to settings.json:

"McpServers": {
  "local-fs": {
    "name": "local-fs",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\YourName\\projects"]
  }
}

After restart, the agent mcp_local-fs will be available with tools:

  • read_file, write_file, list_directory
  • create_directory, move_file, search_files
  • get_file_info

Usage: "Use the filesystem agent to list my project files"