Skip to content

Add documentation for the search tool #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 31, 2025
Merged

Add documentation for the search tool #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7448aba
Add documentation for the search tool
Jul 16, 2025
50640d2
Fix broken links
Jul 16, 2025
6b7d733
Update docs/source/guides/index.mdx
DaleSeo Jul 31, 2025
a33d0df
Update docs/source/guides/index.mdx
DaleSeo Jul 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
In particular, we strongly recommend contract variants when using:

- [GraphOS-managed persisted queries](/apollo-mcp-server/guides#from-graphos-managed-persisted-queries)
- [Introspection](/apollo-mcp-server/guides#from-schema-introspection)
- [Introspection](/apollo-mcp-server/guides#introspection-tools)

Check notice on line 21 in docs/source/best-practices.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/best-practices.mdx#L21 

Link text should be descriptive and match the title of the content it links to when possible.

```suggestion
- [Introspection tools](/apollo-mcp-server/guides#introspection-tools)
```

## Send client name header when using persisted queries

Expand Down
9 changes: 5 additions & 4 deletions docs/source/guides/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,13 +153,14 @@

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.

### From schema introspection
## Introspection tools

For use cases where not all operations can be pre-defined, Apollo MCP Server supports tool creation based on introspection of the graph schema. This allows AI agents to explore a graph and execute operations dynamically.
In addition to defining specific tools for pre-defined GraphQL operations, Apollo MCP Server supports introspection tools that enable AI agents to explore the graph schema and execute operations dynamically.

To enable these schema-aware tools, run the MCP Server with the `introspection` option, which exposes two new tools:
You can enable the following introspection tools:

- `introspect` - returns information about schema types
- `introspect` - allows the AI model to introspect the schema of the GraphQL API by providing a specific type name to get information about, and a depth parameter to determine how deep to traverse the subtype hierarchy. The AI model can start the introspection by looking up the top-level `Query` or `Mutation` type.

Check notice on line 162 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L162 

Use 'enables' instead of 'allows' when referring to functionality a feature provides.

```suggestion
- <code>introspect</code> - enables the AI model to introspect the schema of the GraphQL API by providing a specific type name to get information about, and a depth parameter to determine how deep to traverse the subtype hierarchy. The AI model can start the introspection by looking up the top-level <code>Query</code> or <code>Mutation</code> type.
```
- `search` - allows the AI model to search for type information by providing a set of search terms. This can result in fewer tool calls than `introspect`, especially if the desired type is deep in the type hierarchy of the schema. Search results include all the parent type information needed to construct operations involving the matching type.

Check notice on line 163 in docs/source/guides/index.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/guides/index.mdx#L163 

Use 'enables' instead of 'allows' when referring to functionality a feature provides.

```suggestion
- <code>search</code> - enables the AI model to search for type information by providing a set of search terms. This can result in fewer tool calls than <code>introspect</code>, especially if the desired type is deep in the type hierarchy of the schema. Search results include all the parent type information needed to construct operations involving the matching type.
```
- `execute` - executes an operation on the GraphQL endpoint

The MCP client can use these tools to provide schema information to the model and its context window, and allow the model to execute GraphQL operations based on that schema.
Expand Down
2 changes: 1 addition & 1 deletion docs/source/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@
See the [user guide](/apollo-mcp-server/guides) to learn how to create tools from:
- [Operation files](/apollo-mcp-server/guides#from-operation-files)
- [Persisted query manifests](/apollo-mcp-server/guides/#from-persisted-query-manifests)
- [Schema introspection](/apollo-mcp-server/guides/#from-schema-introspection)
- [Schema introspection](/apollo-mcp-server/guides/#introspection-tools)

Check notice on line 192 in docs/source/quickstart.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/quickstart.mdx#L192 

Link text should match the title of the content it links to for consistency.

```suggestion
- [Introspection tools](/apollo-mcp-server/guides/#introspection-tools)
```

When you are ready, [deploy the MCP server](https://www.apollographql.com/docs/apollo-mcp-server/guides#deploying-the-mcp-server).

Expand Down