모든 GraphQL API를 Claude Code에 연결하는 범용 MCP(Model Context Protocol) 서버입니다. GraphQL 스키마를 인트로스펙션(introspection)하여 각 쿼리와 뮤테이션을 개별 도구로 노출함으로써, Claude가 API와 직접 상호작용할 수 있도록 합니다.
서버가 시작되면 다음을 수행합니다:
작업 디렉토리에서 schema-introspection.json 파일을 찾습니다 (빠르고 네트워크 호출 없음)
파일을 찾을 수 없으면 GRAPHQL_INTROSPECTION_URL에 대해 실시간 인트로스펙션을 실행합니다
쿼리당 하나의 도구(query__<name>)와 뮤테이션당 하나의 도구(mutation__<name>)를 등록합니다
항상 범용 execute_graphql 폴백 도구와 get_type_details 탐색 도구를 등록합니다
Related MCP server: GraphQL MCP Server
Node.js >= 18
npm install -g mcp-graphql-bridgegit clone https://github.com/murilopereira/mcp-graphql-bridge.git
cd mcp-graphql-bridge
npm install
npm run build변수 | 필수 여부 | 설명 |
| 예 | 쿼리 및 뮤테이션에 사용되는 엔드포인트 |
| 예 | 스키마 인트로스펙션에 사용되는 엔드포인트 (위와 동일할 수 있음) |
| 예 | 인증을 위한 Bearer 토큰 |
프로젝트 루트의 .env 파일에 설정할 수 있습니다:
GRAPHQL_API_URL=https://your-api.example.com/graphql
GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql
GRAPHQL_TOKEN=your-bearer-token또는 claude mcp add 명령을 통해 직접 전달할 수도 있습니다 (아래 참조).
기본적으로 서버는 시작 시 실시간으로 스키마를 인트로스펙션하므로 파일이 필요하지 않습니다. API의 프로덕션 환경에서 인트로스펙션이 비활성화되어 있거나 더 빠른 시작 시간을 원하는 경우에만 이 단계를 사용하세요:
curl -s -X POST https://your-api.example.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-bearer-token" \
-d '{"query":"{ __schema { queryType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } type { kind name ofType { kind name ofType { kind name } } } } } mutationType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } type { kind name ofType { kind name ofType { kind name } } } } } } }"}' \
> schema-introspection.jsonnpm에서 설치한 경우:
claude mcp add --transport stdio \
--env GRAPHQL_API_URL=https://your-api.example.com/graphql \
--env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
--env GRAPHQL_TOKEN=your-bearer-token \
graphql-bridge -- mcp-graphql-bridge소스에서 복제한 경우:
claude mcp add --transport stdio \
--env GRAPHQL_API_URL=https://your-api.example.com/graphql \
--env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
--env GRAPHQL_TOKEN=your-bearer-token \
graphql-bridge -- node /absolute/path/to/mcp-graphql-bridge/dist/index.js중요:
mcp-graphql-bridge/index.js가 아닌mcp-graphql-bridge/dist/index.js(컴파일된 결과물)를 사용해야 합니다. TypeScript 소스는 먼저npm run build로 빌드되어야 하며, 진입점은dist/폴더에 있습니다.
.mcp.json 사용)claude mcp add --transport stdio --scope project \
--env GRAPHQL_API_URL=https://your-api.example.com/graphql \
--env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
--env GRAPHQL_TOKEN=your-bearer-token \
graphql-bridge -- mcp-graphql-bridge참고: 절대 경로를 사용하세요. 모든
--env및--transport플래그는 서버 이름 앞에 와야 합니다.
claude mcp list그런 다음 Claude Code 세션에서 /mcp를 실행하여 사용 가능한 서버와 도구를 확인하세요.
도구 | 설명 |
| GraphQL 쿼리 필드당 하나의 도구 |
| GraphQL 뮤테이션 필드당 하나의 도구 |
| 범용 폴백 — 모든 쿼리 또는 뮤테이션 실행 |
| 특정 GraphQL 타입의 필드 탐색 |
모든 작업별 도구는 사용자 지정 GraphQL 선택 세트(예: { id name status })를 제공할 수 있는 특수 __fields 인수를 허용합니다. 생략하면 스칼라 필드만 반환됩니다.
docker build -t mcp-graphql-bridge .claude mcp add --transport stdio \
--env GRAPHQL_API_URL=https://your-api.example.com/graphql \
--env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
--env GRAPHQL_TOKEN=your-bearer-token \
graphql-bridge -- docker run -i --rm \
-e GRAPHQL_API_URL -e GRAPHQL_INTROSPECTION_URL -e GRAPHQL_TOKEN \
mcp-graphql-bridge참고:
-i플래그(-t제외)가 필요합니다. 이는 MCP stdio 프로토콜을 위해 stdin을 열어둡니다.
npm run dev # watch mode: rebuilds and restarts on file changes
npm run build # one-off TypeScript compile
npm start # run the compiled server다음과 같은 오류가 발생하면:
Error: Cannot find module '/path/to/mcp-graphql-bridge/index.js'잘못된 파일을 가리키고 있는 것입니다. TypeScript 소스는 먼저 컴파일되어야 하며, 진입점은 dist/ 폴더에 있습니다:
올바른 경로: /path/to/mcp-graphql-bridge/dist/index.js
잘못된 경로: /path/to/mcp-graphql-bridge/index.js
해결 방법:
npm run build를 실행했는지 확인하세요 (dist/ 폴더 생성)
MCP 구성을 업데이트하여 /dist/index.js로 끝나는 전체 경로를 사용하세요
서버가 시작되지만 "Schema introspection failed"가 표시되면, GraphQL API의 프로덕션 환경에서 인트로스펙션이 비활성화되었을 수 있습니다. 설정 3단계의 curl 명령을 사용하여 schema-introspection.json 파일을 사전 생성하세요.
claude mcp list를 실행하여 서버가 등록되었는지 확인하세요
Claude Code 세션에서 /mcp를 실행하여 사용 가능한 도구를 확인하세요
필요한 모든 환경 변수가 설정되었는지 확인하세요 (GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN)
Execute any GraphQL query or mutation against the API. Use this when no specific tool exists for your operation.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Full GraphQL query or mutation string including selection set | |
| variables | No | Variables for the operation | |
| bearer_token | No | Bearer token to authenticate this request (overrides GRAPHQL_TOKEN) | |
| custom_headers | No | Additional request headers as key-value pairs, e.g. {"X-Tenant-ID": "abc"} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It does not mention potential side effects of mutations, authentication requirements (beyond parameter hints), rate limits, or error handling. The description is too minimal to convey safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences pack purpose and usage guidelines with zero waste, frontloading the key action and fallback use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not explain return format, errors, or the fact that the endpoint is pre-configured. Despite the complexity of a generic GraphQL executor, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 4 parameters have descriptions). The description adds no additional parameter semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute any GraphQL query or mutation against the API', specifying the verb and resource. It distinguishes itself from sibling 'get_type_details' by being a generic executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when no specific tool exists for your operation', providing clear when-to-use guidance. No exclusions, but the instruction is direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get fields of a specific GraphQL type to know what to put in __fields
| Name | Required | Description | Default |
|---|---|---|---|
| typeName | Yes | GraphQL type name, e.g. 'Repository', 'User', 'Issue' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It indicates a read operation, but does not mention error handling (e.g., invalid type name), response structure, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no extraneous text. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits output details. The agent does not know whether the response returns field names, types, or full schema; this is critical given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter with a clear description and examples. The tool description adds no extra meaning beyond prompting usage of '__fields'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets fields of a specific GraphQL type and its purpose in GraphQL introspection. However, it does not differentiate from sibling tool execute_graphql, which may also retrieve type information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'to know what to put in __fields' implies a use case, but there is no explicit guidance on when to use this tool versus execute_graphql, nor any when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.1.0execute_graphql2 fields changedInput schema / properties / bearer_tokenAdded value: +{
+ "description": "Bearer token to authenticate this request (overrides GRAPHQL_TOKEN)",
+ "type": "string"
+}Input schema / properties / custom_headersAdded value: +{
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Additional request headers as key-value pairs, e.g. {\"X-Tenant-ID\": \"abc\"}",
+ "type": "object"
+}get_type_details1 field changedInput schema / properties / typeName / descriptionPrevious value: -"GraphQL type name, e.g. 'Machine', 'WorkOrder', 'Shift'"New value: +"GraphQL type name, e.g. 'Repository', 'User', 'Issue'"v1.0.1execute_graphqlget_type_detailsScored across 2 tools
The two tools serve clearly distinct purposes: executing GraphQL operations vs. retrieving type metadata. No overlap in functionality.
Both tool names follow a consistent verb_noun pattern using snake_case (execute_graphql, get_type_details), making the intent clear and predictable.
For a GraphQL bridge, two tools is minimal but still covers the essential operations of executing queries and exploring types. Slightly under-scoped but reasonable.
The tool surface covers core GraphQL operations (any query/mutation) and type introspection. Minor gaps exist (e.g., no dedicated tool for listing mutations), but the generic execute tool and type details suffice for agents familiar with GraphQL.
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
