Best Practices

Writing your schema for efficient MCP tools

The schema is required for:

• Tool Descriptions: The schema provides type information used to generate tool descriptions. You can override these descriptions by adding comments to your operation files.

• Input Validation: The schema is used to translate GraphQL input types into JSON Schema, ensuring that AI models provide correctly formatted inputs.

• Introspection Support: If you enable the introspection option, the schema is used to provide information about available types and operations to AI models.

Use contract variants to control AI access to graphs

GraphOS contract variants let you deliver different subsets of your graph to different consumers.

When running Apollo MCP Server with GraphOS, use contract variants whenever possible. This allows you to control which parts of your graph are accessible to AI by exposing only the necessary subsets.

In particular, we strongly recommend contract variants when using:

• GraphOS-managed persisted queries

• Introspection

Send client name header when using persisted queries

If you register a persisted query with a specific client name instead of null, you must configure the MCP Server to send the necessary header indicating the client name to the router.

Use the headers option when running the MCP Server to pass the header to the router. The default name of the header expected by the router is apollographql-client-name. To use a different header name, configure telemetry.apollo.client_name_header in router YAML configuration.