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 let your agent check a graph's persisted query list and publish operations to it.

Get Persisted Query List Status

Purpose: Check whether a graph variant has a Persisted Query List (PQL) configured and return its ID, its name, its current build revision, and its operation count. Use this to assess PQL configuration because a production variant with no PQL might be insecure. Pass the list ID to Publish Persisted Queries.

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

Publish Persisted Queries

Purpose: Publish operations to a persisted query list. Operations that you don't mention stay in the list unchanged: your agent passes the operations to add or replace, as well as the operations to remove. Returns the new revision and the total operation count or reports that nothing has changed. Use Get Persisted Query List Status first to find the list ID.

Example: "Add the operations in this manifest to my production persisted query list."

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."

Tools for graph schemas

The tools described in this section let your agent read a variant's full schema and publish or delete a graph.

Get Graph Schema

Purpose: Retrieve the API schema that is currently published to a variant, along with its hash and publication time. The response holds the whole schema and isn't truncated. A large federated graph can exceed 800,000 characters, roughly 200,000 tokens, which is more than the context window of most models. For a federated graph, use Get Subgraph Schema to read one subgraph at a time.

Example: "Fetch the published schema for my staging variant and list its root fields."

Get Supergraph Schema

Purpose: Retrieve the composed supergraph schema of a variant, with the composition ID and any composition errors. The supergraph schema includes the federation directives that the API schema leaves out, and it is larger than the API schema, so the same size limit applies. A variant that isn't federated has no supergraph schema, and the tool returns no result for it.

Example: "Fetch the supergraph schema for my production variant and tell me which subgraph resolves Product.price."

Publish Graph Schema

Purpose: Publish a schema to a variant of a non-federated graph (monograph). For a federated graph, use Publish Subgraph instead. Returns a result code, whether the publish succeeded, a message, and the hash of the published schema. Optionally, your agent can label the publication with a Git branch and commit.

Example: "Publish this schema to my staging variant."

Delete Graph

Purpose: Delete a graph and all of its variants. The deletion is a soft delete: the data isn't removed permanently, and Apollo Support can restore the graph.

Example: "Delete my test graph <GRAPH_ID>."

Tools for contracts

The tools described in this section let your agent read and update contract variants. A contract variant is a filtered view of another variant's schema, built by including and excluding schema elements by tag.

Get Contract Config

Purpose: Retrieve the filter configuration of a contract variant: the tags it includes, the tags it excludes, the source variant it is built from, and a description of the configuration. The description is the only place that states whether the contract hides unreachable types. A variant that is not a contract returns no filter configuration.

Example: "Which tags does my public contract variant include and exclude?"

Publish Contract

Purpose: Create or update a contract variant and start a launch for it. The new filter configuration replaces the previous one in full, so your agent sends the complete include and exclude tag lists, and whether to hide unreachable types. When updating a contract, run Get Contract Config first to keep the settings that you don't want to change. Returns the contract variant and a link to the launch, or the errors that stopped it.

Example: "Add the internal tag to the exclude list of my public contract variant, and keep the rest of its configuration."

Tools for variant READMEs

The tools described in this section let your agent read and replace the README that GraphOS Studio shows on a variant's page.

Get Readme

Purpose: Retrieve the README of a variant, with the time it was last updated and who updated it.

Example: "Show me the README of my production variant."

Publish Readme

Purpose: Replace the README of a variant. The new text replaces the whole README, so if you want to keep part of the current README, run Get Readme first.

Example: "Add a section about rate limits to the README of my production variant."

Tools for schema proposals

The tools described in this section let your agent work with schema proposals: list and read proposals, create a proposal, save a revision of its schema changes, change its status, review it, and comment on it.

Get Proposals

Purpose: List the schema proposals on a graph with their IDs, titles, statuses, authors, source variants, and proposal variants, plus the total count. Filter by status, source variant, or subgraph, and page through the results with a limit and offset. Pass a proposal ID to Get Proposal for full detail.

Example: "List the open schema proposals on my graph."

Get Proposal

Purpose: Retrieve a single schema proposal: its title, description, status, author, source variant, and proposal variant, its latest revision with the revision's schema check and launch, and every review. The other proposal tools use the IDs that this tool returns.

Example: "What's the status of proposal <PROPOSAL_ID>, and did its latest revision pass schema checks?"

Create Proposal

Purpose: Create a schema proposal against a source variant. GraphOS creates a proposal variant that starts as a copy of the source variant's schema, and the proposal starts as a draft. Use Publish Proposal Revision next to add schema changes.

Example: "Create a proposal against my production variant called 'Add product ratings'."

Publish Proposal Revision

Purpose: Save a new revision of a proposal by publishing changed subgraph schemas to its proposal variant. GraphOS composes the proposal variant and runs schema checks on it. The source variant doesn't change. If someone else saved a revision in the meantime, the call fails, and your agent reads the proposal again before retrying. GraphOS saves a revision even when its schema doesn't compose, so your agent checks the revision's schema check and launch status with Get Proposal afterward.

Example: "Add a rating field to Product in the reviews subgraph and save it as a revision of my proposal."

Update Proposal Status

Purpose: Change the status of a proposal—for example, from draft to open or closed. GraphOS sets a proposal to approved only when it has as many approvals as the graph requires, and it doesn't let your agent set a proposal to implemented.

Example: "Open my proposal for review."

Review Proposal

Purpose: Approve or reject the latest revision of a proposal, with an optional comment. Only a requested reviewer can review, and a new review replaces the reviewer's earlier one.

Example: "Approve the latest revision of proposal <PROPOSAL_ID> with the comment 'Looks good'."

Add Proposal Comment

Purpose: Add a comment to a proposal. The comment can be a general comment, a reply to another comment, or a comment on a specific schema change, like a single field in a subgraph.

Example: "Comment on the new Product.rating field in my proposal and ask whether it should be nullable."

Tools for graph artifacts

The tools described in this section let your agent read and tag graph artifacts. A graph artifact is the build output, like the composed supergraph schema, that GraphOS Router fetches from Apollo's OCI registry. A tag lets Router fetch an artifact by name instead of by digest.

Get Graph Artifact

Purpose: Retrieve a graph artifact by its digest: its ID, status, build errors, timestamps, variant, the launch that produced it, its registry location, and its tags.

Example: "Is the graph artifact with digest <DIGEST> complete, and which tags point to it?"

Get Graph Artifact Tags

Purpose: List the graph artifact tags on a graph and the artifact that each tag points to. Optionally, filter by variant. Use this to find a tag or a digest before running the other graph artifact tools.

Example: "List the graph artifact tags for my production variant."

Tag Graph Artifact

Purpose: Assign a tag to a graph artifact. If the tag already exists, it moves to this artifact, and a router that fetches by that tag receives the new artifact.

Example: "Tag the artifact with digest <DIGEST> as release-candidate."

Untag Graph Artifact

Purpose: Delete a tag and its history from a graph. The artifact itself stays. Tags that Apollo manages, like a variant's latest tag, can't be deleted.

Example: "Remove the release-candidate tag from my graph."

Tools for API keys

The tools described in this section let your agent list, create, rename, and delete the API keys of your organization.

Get API Keys

Purpose: List your organization's API keys with each key's ID, name, type, creation, expiration, last use, revocation time, and the resources it can access. Key values are never returned. Filter by status and type.

Example: "Which API keys in my organization have never been used?"

Create API Key

Purpose: Create an API key for your organization. An operator key has full access to the organization, and a subgraph key has access only to the subgraphs you list. The response contains the new key's value.

Example: "Create a subgraph key named products-ci that can publish to the products subgraph on my production variant."

Rename API Key

Purpose: Rename an API key. The key's value and its access don't change.

Example: "Rename the key old-ci to products-ci."

Delete API Key

Purpose: Delete an API key. Every client that uses the key stops authenticating, and the deletion can't be undone.

Example: "Delete the API key <KEY_ID>."

Tools for licenses

The tools described in this section let your agent fetch your organization's offline Enterprise license.

Get Offline License

Purpose: Fetch the offline Enterprise license for the organization that owns a graph. GraphOS Router uses this license to enable Enterprise features while it runs disconnected from GraphOS. Returns no license when your organization doesn't have offline licenses enabled.

Example: "Fetch the offline license for my graph."