Skip to content

Document additional discovery methods #6010

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
ethanpalm merged 1 commit into from
May 27, 2026
Merged

Document additional discovery methods #6010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 2 additions & 0 deletions ai/model-context-protocol.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,8 @@ Mintlify hosts a discovery document at `/.well-known/mcp` for agents and tools t
| `servers[].name` | Identifier for the server entry. |
| `servers[].authentication` | Authentication method for the server entry. |

For agent-readiness, the same discovery document is also available at `/.well-known/mcp.json`. Mintlify additionally serves an MCP server card at `/.well-known/mcp/server-card.json` and a list of server cards at `/.well-known/mcp/server-cards.json`. All discovery endpoints are served automatically and don't require configuration.

### Enable authenticated MCP

If your documentation requires authentication, your MCP server requires users to authenticate before connecting. When a user adds your MCP server URL to their AI tool, they must log in with their existing credentials. After authenticating, a redirect sends them back to their tool. The MCP server only returns content each user has permission to access based on their [user groups](/deploy/authentication-setup).
Expand Down
14 changes: 14 additions & 0 deletions ai/skillmd.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
Teach your users how to use `skill.md` files with agents so that they have better results using your product with their AI tools.
</Tip>

## `skill.md` structure

Check warning on line 49 in ai/skillmd.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/skillmd.mdx#L49 

'structure' should use sentence-style capitalization.

Mintlify generates a `skill.md` file following the [agentskills.io specification](https://agentskills.io/specification). The generated file includes:

Expand Down Expand Up @@ -105,7 +105,7 @@
docs.json
```

Mintlify resolves symlinks during deployment, so the skill files are discovered and served as if they were directly inside `.mintlify/skills/`. This works with both directory symlinks and individual skill symlinks.

Check warning on line 108 in ai/skillmd.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/skillmd.mdx#L108 

In general, use active voice instead of passive voice ('are discovered').

### Frontmatter fields

Expand Down Expand Up @@ -191,3 +191,17 @@
### Individual skill files

`GET /.well-known/skills/{name}/skill.md` returns the `skill.md` file for a specific skill identified by its slugified name from the index.

## Agent card

Mintlify hosts an [Agent-to-Agent (A2A)](https://a2aproject.github.io/A2A/latest/) agent card at `/.well-known/agent-card.json`. The agent card is a standardized JSON document that helps A2A-compatible agents discover your documentation site and available skills in a single request.

`GET /.well-known/agent-card.json` returns a JSON document following the A2A agent card 0.2.0 schema. Each entry in the `skills` array corresponds to a skill from your skills discovery endpoints.

A2A-compatible agents fetch `/.well-known/agent-card.json` to discover your site by name and description, follow `documentationUrl` to retrieve human-readable content, and iterate over `skills` to fetch each `skill.md` file.

<Note>
If you use a [reverse proxy](/deploy/reverse-proxy), configure it to forward `/.well-known/agent-card.json` to your Mintlify subdomain.
</Note>

The agent card complements [MCP](/ai/model-context-protocol) by providing a lightweight discovery layer that does not require establishing a session.
Loading