On this page

Gateway: MCP Server

Expose your GraphQL API to AI agents as MCP tools and resources with the Hive Gateway MCP plugin.

The Model Context Protocol (MCP) is the standard AI agents use to discover and call external tools. With the @graphql-hive/plugin-mcp plugin, Hive Gateway becomes an MCP server: you pick the GraphQL operations you want to expose, and each one becomes a tool that agents can list and execute, complete with typed input and output schemas derived from your supergraph.

MCP (JSON-RPC)

GraphQL

AI agent

Hive Gateway
/mcp endpoint

Your subgraphs

The gateway takes care of loading the schema, generating input and output schemas, validating arguments and formatting responses. You only define which operations become tools. The plugin implements the initialize, tools/list, tools/call, resources/list, resources/read and resources/templates/list MCP methods.

Installation

npm i @graphql-hive/plugin-mcp

The package ships both CommonJS and ESM builds and needs graphql as a peer dependency. Langfuse is an optional peer dependency, only needed when you use the built-in Langfuse description provider.

Quick start

Register the plugin with the operations you want to expose. The simplest tool is an inline query.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
import { useMCP, type MCPConfig } from '@graphql-hive/plugin-mcp'

const mcp: MCPConfig = {
  name: 'my-api',
  tools: [
    {
      name: 'get_users',
      source: {
        type: 'inline',
        query: `query ($limit: Int) { users(limit: $limit) { id name } }`
      }
    }
  ]
}

export const gatewayConfig = defineConfig({
  plugins: ctx => [useMCP(ctx, mcp)]
})

Then start the gateway as usual, for example with hive-gateway supergraph.

gateway.ts
import { createGatewayRuntime } from '@graphql-hive/gateway-runtime'
import { useMCP } from '@graphql-hive/plugin-mcp'

const gateway = createGatewayRuntime({
  supergraph: 'supergraph.graphql',
  plugins: ctx => [
    useMCP(ctx, {
      name: 'my-api',
      tools: [
        {
          name: 'get_users',
          source: {
            type: 'inline',
            query: `query ($limit: Int) { users(limit: $limit) { id name } }`
          }
        }
      ]
    })
  ]
})

The MCP endpoint is served at /mcp next to your GraphQL endpoint. Change it with the path option.

Define tools with directives

Instead of listing tools in the configuration, you can annotate named operations in .graphql files with the @mcpTool directive and point the plugin at them:

operations/weather.graphql
query GetWeather($location: String!)
@mcpTool(name: "get_weather", description: "Get current weather") {
  weather(location: $location) {
    temperature
    conditions
  }
}
gateway.config.ts
useMCP(ctx, {
  name: 'my-api',
  operationsPath: './operations'
})

Every operation carrying @mcpTool is registered as a tool automatically. Operations without the directive stay available as sources for tools declared in the configuration. All operations must be named; anonymous operations are not supported. The Tools page covers the @mcpDescription and @mcpHeader directives as well.

Define tools in YAML or JSON

The configuration object is plain data, so it can live in a YAML or JSON file that you load and pass to useMCP:

mcp.yaml
name: weather-api
version: 1.0.0

tools:
  - name: get_weather
    source:
      type: inline
      query: |
        query GetWeather($location: String!) {
          weather(location: $location) {
            temperature
            conditions
          }
        }
    tool:
      title: Current Weather

Try it out

MCP speaks JSON-RPC over HTTP, so curl is enough to check the server:

List the tools
curl http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Call a tool
curl http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_weather","arguments":{"location":"London"}}}'

Point any MCP client (an IDE assistant, an agent framework, or the MCP Inspector) at http://localhost:4000/mcp to use the tools interactively.

Next steps