fix(graphql): handle error responses and deprecate dedicated server (#430)

* fix: handle path-less GraphQL errors (#402)

* fix: address PR #430 review feedback

- mock GraphQL API requests with the shared MSW server
- fail on unhandled outbound requests and assert request details

* chore(graphql): deprecate dedicated MCP server

- direct users to the Cloudflare API MCP server
- remove the GraphQL server from public listings
- tighten GraphQL response diagnostics against the specification

---------

Co-authored-by: agent-think[bot] <agent-think[bot]@users.noreply.github.com>
Co-authored-by: Matt Carey <mcarey@cloudflare.com>
Co-authored-by: Matt <77928207+mattzcarey@users.noreply.github.com>

Author: agent-think[bot]

.changeset/deprecate-graphql-mcp.md

@@ -0,0 +1,7 @@
+---
+"graphql-mcp-server": patch
+---
+
+Deprecate the dedicated GraphQL MCP server in favor of the Cloudflare API MCP server at https://mcp.cloudflare.com/mcp. The replacement supports GraphQL queries, variables, and schema introspection through Code Mode.
+
+The existing tools continue to work for now. The server exposes the migration notice through MCP instructions and is no longer advertised in the root server list or `server.json`.

.changeset/graphql-error-responses.md

@@ -0,0 +1,5 @@
+---
+"graphql-mcp-server": patch
+---
+
+Surface GraphQL API errors with optional paths and extensions instead of throwing Zod validation errors, and pass through unrecognized upstream response shapes.

README.md

@@ -24,7 +24,6 @@ The following servers are included in this repository:
 | [**Digital Experience Monitoring server**](/apps/dex-analysis) | Get quick insight on critical applications for your organization                                | `https://dex.mcp.cloudflare.com/mcp`           |
 | [**Cloudflare One CASB server**](/apps/cloudflare-one-casb)    | Quickly identify any security misconfigurations for SaaS applications to safeguard users & data | `https://casb.mcp.cloudflare.com/mcp`          |
 | [**Radar server**](/apps/radar)                                | Explore Cloudflare Radar internet insights                                                      | `https://radar.mcp.cloudflare.com/mcp`         |
-| [**GraphQL server**](/apps/graphql)                            | Get analytics data using Cloudflare’s GraphQL API                                               | `https://graphql.mcp.cloudflare.com/mcp`       |
 | [**Cloudflare Blog server**](/apps/cloudflare-blog)            | Search and read posts from the Cloudflare Blog                                                  | `https://blog.mcp.cloudflare.com/mcp`          |
 | [**Demo Day server**](/apps/demo-day)                          | Demonstrate a minimal Cloudflare MCP server                                                     | `https://demo-day.mcp.cloudflare.com/mcp`      |
 

apps/graphql/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Setup
+
+> This server is deprecated. See [`README.md`](./README.md) for the migration path to [`mcp.cloudflare.com/mcp`](https://mcp.cloudflare.com/mcp). Bug fixes are welcome, but new features should be proposed in the unified [`cloudflare/mcp`](https://github.com/cloudflare/mcp) repository.
+
+You can run the server locally when maintaining existing behavior.
+
+## Local development
+
+1. Create a `.dev.vars` file in the project root.
+
+   Cloudflare employees can use OAuth credentials:
+
+   ```text
+   CLOUDFLARE_CLIENT_ID=your_development_cloudflare_client_id
+   CLOUDFLARE_CLIENT_SECRET=your_development_cloudflare_client_secret
+   ```
+
+   External contributors can use a development API token:
+
+   ```text
+   DEV_DISABLE_OAUTH=true
+   DEV_CLOUDFLARE_API_TOKEN=your_development_api_token
+   ```
+
+2. Start the local development server:
+
+   ```bash
+   npx wrangler dev
+   ```
+
+3. Open the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) and connect to `http://localhost:8976/mcp`.
+
+## Deploying the Worker (Cloudflare employees only)
+
+Set secrets with Wrangler:
+
+```bash
+npx wrangler secret put CLOUDFLARE_CLIENT_ID -e <ENVIRONMENT>
+npx wrangler secret put CLOUDFLARE_CLIENT_SECRET -e <ENVIRONMENT>
+```
+
+Create the OAuth KV namespace, then add its ID to `wrangler.jsonc`:
+
+```bash
+npx wrangler kv namespace create "OAUTH_KV"
+```
+
+Deploy the server:
+
+```bash
+npx wrangler deploy -e <ENVIRONMENT>
+```

apps/graphql/README.md

@@ -1,13 +1,34 @@
 # Cloudflare GraphQL MCP Server
 
-This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP
-connections, with Cloudflare OAuth built-in. It integrates tools powered by the [Cloudflare GraphQL API](https://developers.cloudflare.com/analytics/graphql-api/) to provide insights and utilities for your Cloudflare account.
+## Deprecated
 
-The `/mcp` and `/sse` URLs use the same stateless SDK v2 handler and create a fresh server with request-scoped auth/account context for every request. `/sse` is not the deprecated HTTP+SSE transport. OAuth remains durable security state; no MCP protocol session or protocol Durable Object is retained.
+This dedicated MCP server is deprecated. Use the Cloudflare API MCP server at [`mcp.cloudflare.com/mcp`](https://mcp.cloudflare.com/mcp) instead. It supports the Cloudflare GraphQL Analytics API, including queries, variables, and schema introspection.
 
-## Available Tools
+The GraphQL Analytics API itself is not deprecated. Only this dedicated MCP server is being retired.
 
-Currently available tools:
+Configure the replacement server in your MCP client:
+
+```json
+{
+	"mcpServers": {
+		"cloudflare-api": {
+			"url": "https://mcp.cloudflare.com/mcp"
+		}
+	}
+}
+```
+
+The replacement uses [Code Mode](https://blog.cloudflare.com/code-mode-mcp/). Its `search` and `execute` tools cover the full Cloudflare API, including `POST /client/v4/graphql`. See the [GraphQL Analytics API example](https://github.com/cloudflare/mcp#graphql-analytics-api) in [`cloudflare/mcp`](https://github.com/cloudflare/mcp).
+
+The tools below still work for now, but no new features will be added. Please migrate to the Cloudflare API MCP server.
+
+---
+
+This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP connections, with Cloudflare OAuth built in. It integrates tools powered by the [Cloudflare GraphQL Analytics API](https://developers.cloudflare.com/analytics/graphql-api/) to provide insights and utilities for your Cloudflare account.
+
+Until retirement, the `/mcp` and `/sse` URLs use the same stateless SDK v2 handler and create a fresh server with request-scoped auth and account context for every request. `/sse` is not the deprecated HTTP+SSE transport. OAuth remains durable security state; the server retains no MCP protocol session or protocol Durable Object.
+
+## Available tools
 
 | **Category**                | **Tool**                  | **Description**                                                                                 |
 | --------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
@@ -18,7 +39,7 @@ Currently available tools:
 | **GraphQL Query Execution** | `graphql_query`           | Execute a GraphQL query against the Cloudflare API                                              |
 | **GraphQL API Explorer**    | `graphql_api_explorer`    | Generate a Cloudflare [GraphQL API Explorer](https://graphql.cloudflare.com/explorer) link      |
 
-### Prompt Examples
+### Prompt examples
 
 - `Show me HTTP traffic for the last 7 days for example.com`
 - `Show me which GraphQL datatype I need to use to query firewall events`
@@ -27,4 +48,8 @@ Currently available tools:
 
 ## Connect to the MCP server
 
+> This connection information is retained for existing users. New users should configure [`mcp.cloudflare.com/mcp`](https://mcp.cloudflare.com/mcp) as shown above.
+
 Connect your MCP client directly to `https://graphql.mcp.cloudflare.com/mcp`. If prompted, complete the Cloudflare OAuth flow in your browser. The tools become available after authorization.
+
+Bug fixes are still accepted. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup. New features should be proposed in the unified [`cloudflare/mcp`](https://github.com/cloudflare/mcp) repository.

apps/graphql/package.json

@@ -20,6 +20,7 @@
 	"devDependencies": {
 		"@cloudflare/vitest-pool-workers": "0.16.11",
 		"@types/node": "22.15.17",
+		"msw": "2.14.6",
 		"prettier": "3.5.3",
 		"typescript": "5.5.4",
 		"vitest": "4.1.8",

apps/graphql/src/graphql.app.ts

@@ -7,6 +7,9 @@ import { registerGraphQLTools } from './tools/graphql.tools'
 
 import type { Env } from './graphql.context'
 
+export const DEPRECATION_INSTRUCTIONS =
+	'DEPRECATED: Use the Cloudflare API MCP server at https://mcp.cloudflare.com/mcp instead; it supports the GraphQL Analytics API.'
+
 const GraphQLScopes = {
 	...RequiredScopes,
 	'account:read': 'See your account info such as account details, analytics, and memberships.',
@@ -16,6 +19,7 @@ const GraphQLScopes = {
 const app = createAuthenticatedMcpApp<Env>({
 	serviceHostnames: ['graphql-staging.mcp.cloudflare.com', 'graphql.mcp.cloudflare.com'],
 	scopes: GraphQLScopes,
+	serverOptions: { instructions: DEPRECATION_INSTRUCTIONS },
 	createSentry: ({ env, executionCtx, request, props }) =>
 		props?.type === 'user_token'
 			? initSentryWithUser(env, executionCtx, props.user.id, request)