GraphOS MCP Server Tools

This page is a reference for all available tools in GraphOS MCP Server. Each tool can be used individually or chained together by your agent to answer more complex questions about your graphs. Before using any of these tools, make sure you've completed the GraphOS MCP Server installation.

Get started with example prompts

Try some of these prompts to get started:

List my graphs and tell me which ones need the most attention.

Is my graph <GRAPH_ID> healthy? Run the relevant checks and summarize findings as Attention Required, Review Recommended, or What's Working Well.

Perform a full health check on <GRAPH_ID>: schema composition, lint, and deployment stability. Prioritize the issues you find by severity.

For <GRAPH_ID> check the latest launch and lint results, and tell me what needs attention.

Scan my org <ORG_ID> and flag any graphs that have composition errors or lint errors right now.

For <GRAPH_ID>, cross-reference the top operations with their latency/error metrics. Are any high-traffic operations that are also slow or failing?

For <GRAPH_ID>, which clients and client versions send the most traffic, and is any one of them responsible for a disproportionate share of the errors?

Tools for Apollo documentation

The tools described in this section give your agent access to Apollo's official documentation.

Apollo Docs Search

Purpose: Search across Apollo's official documentation to find the most relevant guides, examples, and best practices for GraphQL, GraphOS, schema design, deployment best practices, connectors, and more.

Example: "How do I enable entity caching with the Apollo Router?"

Result:

Apollo Docs Read

Purpose: Retrieve the full Markdown content of any Apollo documentation page so your agent can go beyond code snippets and provide complete, detailed guidance.

Example: "Fetch the Router YAML config reference and list the top level properties."

Result:

Apollo Connectors Spec

Purpose: Access the official specification for Apollo Connectors, giving your agent the data it needs to create and modify Connectors in a schema.

Examples: "Add weather details to my schema using https://api.weather.gov so I can expose weather conditions for airport cities."

Result: The output is too large to show, but your agentic coding tool still uses the Apollo Connectors Spec tool to generate a graph that integrates with the https://api.weather.gov REST API.

Tools to retrieve graph information

The tools described in this section give your agent access to your organization's graphs and variant details.

Get My Identity

Purpose: Resolve the caller's identity and any organizations their API key belongs to. Use this when you haven't yet provided an organization or graph ID—the returned account and organization ID can be passed to subsequent tool calls.

Get Variant Details

Purpose: Retrieve data about a graph variant such as: its identifier, federation version, the URL of its GraphQL endpoint, and its subgraphs.

Example: "Show the federation version and subgraphs for my production variant."

Tools for launches

The tools described in this section give your agent visibility into the deployment history of your graph variants.

Get Latest Launch

Purpose: Inspect the most recent launch for a graph variant: status, completion time, subgraph changes, composition errors, and a schema diff summary versus the previous launch (additions, removals, edits, deprecations, and affected operations). Also returns the latest approved launch for comparison.

Example: "Did the latest launch on my graph have any composition errors? Any deprecations in the last schema change?"

Get Launch

Purpose: Inspect a single launch by ID for full detail: status, timestamps, which subgraphs changed, composition errors, and the schema diff summary. Use this to drill into a specific launch—for example, a failed or superseded launch found via Get Launch History.

Example: "What composition errors caused launch abc123 to fail?"

Get Launch History

Purpose: Retrieve recent launches for a graph variant (most recent first) to detect deployment instability such as repeated failures or frequent superseded launches. Each entry includes the launch ID, status, and timestamps so you can identify a specific launch and drill into it with Get Launch.

Example: "Have the recent launches on my production variant been stable, or were there repeated failures?

Tools for observability and metrics

The tools described in this section give your agent access to traffic and performance data for your graphs.

By default, each of these tools aggregates the entire requested time window into a single row per operation, subgraph, or client. If you prefer, however, your agent can instead request per-day, per-hour, or per-minute buckets to monitor how a metric changes over time.

Sub-day buckets cover shorter time periods: Per-hour data requires a window of seven days or less, starting within the last 90 days. Per-minute data requires a window of one day or less, starting within the last 30 days. Aggregated and per-day results exclude the most recent day, so use per-hour or per-minute buckets to inspect the most recent traffic.

Get Top Operations

Purpose: Identify the most-used operations on a graph variant for a given time range, with request counts, types, and signatures. Use this to find high-traffic operations, detect unused operations, and prioritize findings by traffic impact.

Example: "What are the 20 most-used operations on my production graph over the last week, by request count?"

Get Operation Metrics

Purpose: Retrieve top operations by usage and health for a graph over a time window. Includes request count, p50 latency, p99 latency, and error count per operation. Rank by busiest, most error-prone, or slowest operations. You can also narrow the results to specific variants or clients.

Example: "Show me request counts and p99 latency trends for my graph's operations over the last 30 days. Flag anything with a spike."

Get Subgraph Metrics

Purpose: Retrieve top subgraphs and connectors by traffic and health for a graph over a time window. Includes fetch count, p50 fetch latency, p99 fetch latency, and fetch error count per subgraph. Rank by busiest, most error-prone, or slowest subgraphs. You can also narrow the results to specific variants, subgraphs, or clients.

Example: "Which of my subgraphs have the highest error rates this month?"

Get Client Metrics

Purpose: Break down a graph's traffic by client over a time window. Returns request count, p50 latency, p99 latency, and error count for each combination of client name, client version, and operation so you can see what clients and versions are calling your graph and which of them drive errors or latency. Clients that don't report a name and version appear with those columns empty. Rank by busiest, most error-prone, or slowest. You can also narrow the results to specific variants or operations.

Example: "Which client versions are still calling my production graph, and are any of them responsible for most of the errors?"

Tools for persisted queries

The tools described in this section give your agent access to your graph's persisted query lists.

Get Persisted Query List Status

Purpose: Check whether a graph variant has a Persisted Query List (PQL) configured and return its current build revision and operation count. Use this to assess PQL configuration—a production variant with no PQL may have a security gap.

Example: "Does my production variant have a persisted query list configured?"

Tools for schema linting

The tools described in this section give your agent access to your graph's schema linting results, and run a schema lint check.

Get Lint Results

Purpose: Retrieve schema lint violations from a graph's most recent schema checks. Returns each diagnostic's coordinate, severity level, message, rule, and source location, plus error, warning, total, and ignored counts. Use this to assess schema quality and identify naming or best-practice violations.

Example: "Are there any schema lint violations in my graph? Show errors before warnings."

Lint Schema

Purpose: Run a lint check on your schema against your graph's lint rules and return each diagnostic's coordinate, severity level, message, rule, and source location, plus the error, warning, total, and ignored counts. Optionally, you can supply a base schema to report only the diagnostics that the new schema introduces. Nothing is published to the graph.

Example: "Run a lint check on this schema and show me only the new violations."

Tools for schema checks

The tools described in this section let your agent read previous schema checks, run schema checks, and validate client operations against a published schema.

Get Schema Checks

Purpose: List previous schema checks for a graph, most recent first. Each entry includes the check ID, status, timestamps, the subgraph that was checked, the variant it ran against, the commit, and the status of each task in the run. Filter by status, subgraph, branch, variant, author, or check ID, and page through the results with a limit and offset. Use this to find a check, then pass its ID to Get Check Results.

Example: "Show the schema checks that failed on my graph this week."

Get Check Results

Purpose: Read the outcome of a single check run: the overall status, and for each task in the run the composition errors, the lint diagnostics, the schema changes with the client operations they affect, the downstream variant results, and the custom check violations. Use this after Get Schema Checks gives you a check ID.

Example: "Why did check 509219cd fail, and which client operations would break?"

Run Schema Check

Purpose: Run a schema check of a proposed schema against a variant. Use this for a monograph or supergraph schema. The check runs in the background, so the tool returns a check ID and a link to the results in GraphOS. Pass the check ID to Get Check Results to read the result.

Example: "Check this schema against my production variant, then show me the results."

Run Subgraph Check

Purpose: Runs a schema check of a proposed subgraph schema against a variant. The check runs in the background, so the tool returns a check ID and a link to the results in GraphOS. Pass the check ID to Get Check Results to read the result.

Example: "Check my proposed changes to the products subgraph."

Validate Operations

Purpose: Validate client GraphQL operations against a variant's published schema and return each problem's type, code, description, and the operation it came from. Use this to check whether client operations still work against a schema. Nothing is published.

Example: "Are the operations in my client still valid against the production schema?"

Tools for subgraphs

The tools described in this section let your agent read a subgraph's schema and change which subgraphs a variant contains.

Get Subgraph Schema

Purpose: Retrieve a subgraph's published schema from a variant, with its routing URL, revision, and last update time. Retrieves one subgraph at a time; a supergraph document is much larger and can exceed the context window of the model. Use Get Variant Details first if you do not know the subgraph names.

Example: "Show me the schema for the products subgraph on my production variant."

Publish Subgraph

Purpose: Publish a subgraph schema to a variant, which triggers composition. Returns whether the subgraph was created or updated, any composition errors, and the launch that started. Provide the routing URL when you add a new subgraph or need to update the subgraph's endpoint. Run the Run Subgraph Check tool first to see the impact on client operations.

Example: "Publish this schema to the products subgraph on my staging variant."

Delete Subgraph

Purpose: Remove a subgraph from a variant, which triggers composition and a new launch. Returns the composition errors that the removal causes. If you enable the dry run option, the tool will not remove the subgraph but instead reports the composition result that the removal would produce. Apollo recommends running this tool with the dry run option enabled first before proceeding.

Example: "What would break if I removed the inventory subgraph? Do a dry run first." Then, if the dry run is successful, you can follow up with "Remove the inventory subgraph."