docs: Mention Mintlify generated agent skills

[richardkmichael]

Description

Add Mintlify generated agent skill installation instructions to docs.

Contribution type

• Bug fix (simple, well-scoped fix for a clearly broken behavior)
• Documentation improvement
• Enhancement (maintainers typically implement enhancements — see CONTRIBUTING.md)

Checklist

• This PR addresses an existing issue (or fixes a self-evident bug)
• I have read CONTRIBUTING.md
• I have added tests that cover my changes
• I have run uv run prek run --all-files and all checks pass
• I have self-reviewed my changes
• If I used an LLM, it followed the repo's contributing conventions (not generic output)

[richardkmichael]

As a draft, for opinions.

I always use the fastmcp docs MCP server. More automated help for agents would be great.

I noticed the MCP Apps spec repo ships agent skills for working with MCP Apps. Helpful, but obviously not correct for FastMCP.

Mintlify just added agent skill generation from docs. See below for the generated FastMCP skill.

I have yet to use it, but seems a good start? Could be off in a few places (e.g., Claude Desktop integration guidance to STDIO is questionable.)

It's also possible to define a custom SKILL.md, or even multiple skills via the agent skill discovery spec.

If/where there are improvements or more content, changing the docs themselves could be a way forward, so the auto-generated Mintlify process could still be used (instead of needing to maintain a custom file).

Multiple skills does seem quite helpful though; maybe an area for contribution.

The `SKILL.md` generated by Mintlify

---
name: Fast Mcp
description: Use when building MCP servers and clients, integrating with LLMs, deploying services, configuring authentication, or working with tools, resources, and prompts. Reach for this skill when agents need to create MCP applications, connect to MCP servers, handle authentication, deploy servers, or troubleshoot MCP protocol issues.
metadata:
    mintlify-proj: fastmcp
    version: "1.0"
---

# FastMCP Skill Reference

## Product Summary

FastMCP is the standard Python framework for building Model Context Protocol (MCP) applications. MCP connects LLMs to tools, data, and services. FastMCP provides decorators (`@mcp.tool`, `@mcp.resource`, `@mcp.prompt`), a programmatic client, CLI tools, and production features like authentication, middleware, composition, and HTTP deployment.

**Key files and commands:**
- Server definition: `from fastmcp import FastMCP; mcp = FastMCP("name")`
- Configuration: `fastmcp.json` (declarative server config)
- CLI: `fastmcp run server.py`, `fastmcp list`, `fastmcp call`, `fastmcp install`
- Client: `from fastmcp import Client`
- Transports: STDIO (default, local), HTTP (network), SSE (legacy)
- Primary docs: https://gofastmcp.com

## When to Use

Reach for FastMCP when:
- Building an MCP server to expose tools, resources, or prompts to LLMs
- Connecting a Python application to any MCP server (client-side)
- Deploying an MCP server for remote access (HTTP transport)
- Securing an MCP server with OAuth or token verification
- Composing multiple servers or providers into one
- Generating MCP servers from OpenAPI specs or FastAPI apps
- Testing MCP servers during development
- Running background tasks with progress tracking
- Integrating with Claude Desktop, Cursor, Gemini CLI, or other MCP clients

## Quick Reference

### Server Decorators

| Decorator | Purpose | Returns |
|-----------|---------|---------|
| `@mcp.tool` | Expose a function as a callable tool | Tool result (any type) |
| `@mcp.resource` | Expose static or templated data | String or ResourceResult |
| `@mcp.prompt` | Expose a reusable message template | String or list[Message] |

### CLI Commands

| Command | Purpose |
|---------|---------|
| `fastmcp run server.py` | Run server with STDIO transport |
| `fastmcp run server.py --transport http --port 8000` | Run with HTTP transport |
| `fastmcp list server.py` | List all tools, resources, prompts |
| `fastmcp call server.py tool_name arg1=value1` | Execute a tool from CLI |
| `fastmcp install --claude-desktop server.py` | Register with Claude Desktop |
| `fastmcp discover` | Find configured servers in editor configs |

### Configuration (fastmcp.json)

```json
{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "server.py",
    "entrypoint": "mcp"
  },
  "deployment": {
    "transport": "http",
    "host": "127.0.0.1",
    "port": 8000,
    "log_level": "INFO"
  }
}
```

### Transport Selection

| Transport | Use Case | Clients |
|-----------|----------|---------|
| STDIO | Local development, desktop apps | Claude Desktop, Cursor, CLI |
| HTTP | Network access, multiple clients, remote deployment | Web clients, remote LLMs |
| SSE | Legacy only—avoid in new projects | Deprecated |

### Dependency Injection

```python
from fastmcp import FastMCP, Context

mcp = FastMCP("app")

@mcp.tool
async def my_tool(ctx: Context) -> str:
    await ctx.info("Logging message")
    await ctx.report_progress(50)  # Progress 0-100
    return "result"
```

### Client Usage

```python
from fastmcp import Client

async with Client("http://localhost:8000/mcp") as client:
    tools = await client.list_tools()
    result = await client.call_tool("tool_name", {"arg": "value"})
    resource = await client.read_resource("resource://path")
    prompt = await client.get_prompt("prompt_name", {"arg": "value"})
```

## Decision Guidance

### When to Use STDIO vs HTTP

| Scenario | Transport | Reason |
|----------|-----------|--------|
| Local development, single user | STDIO | Simpler, no network overhead |
| Claude Desktop integration | STDIO | Desktop apps expect STDIO |
| Multiple concurrent clients | HTTP | STDIO spawns new process per client |
| Remote deployment, cloud | HTTP | Network accessible, scalable |
| Testing in CI/CD | STDIO | Faster, no port binding |

### When to Use Decorators vs Providers

| Approach | Use When |
|----------|----------|
| `@mcp.tool`, `@mcp.resource`, `@mcp.prompt` | Writing custom logic in Python |
| `OpenAPIProvider` | Wrapping existing REST APIs |
| `FileSystemProvider` | Discovering tools from directory structure |
| `ProxyProvider` | Proxying remote MCP servers |
| `SkillsProvider` | Exposing agent skill files as resources |

### When to Use Composition vs Single Server

| Pattern | Use When |
|---------|----------|
| Single server | Simple use case, all logic in one place |
| Mounted servers | Organizing related tools, reusing servers |
| Providers | Dynamically sourcing components from multiple sources |

## Workflow

### Building a Basic Server

1. **Create server file** with decorators:
   ```python
   from fastmcp import FastMCP
   
   mcp = FastMCP("MyServer")
   
   @mcp.tool
   def add(a: int, b: int) -> int:
       """Add two numbers"""
       return a + b
   
   if __name__ == "__main__":
       mcp.run()
   ```

2. **Test locally**: `fastmcp run server.py` or `python server.py`

3. **List components**: `fastmcp list server.py`

4. **Call tools**: `fastmcp call server.py add a=5 b=3`

5. **Register with client**: `fastmcp install --claude-desktop server.py`

### Deploying to HTTP

1. **Create fastmcp.json** with HTTP transport config
2. **Run with CLI**: `fastmcp run server.py --transport http --port 8000`
3. **Or call in code**: `mcp.run(transport="http", host="0.0.0.0", port=8000)`
4. **Access at**: `http://your-server:8000/mcp`

### Adding Authentication

1. **Choose provider** (Auth0, GitHub, Azure, etc.)
2. **Configure auth** in FastMCP:
   ```python
   from fastmcp.server.auth.providers.github import GitHubProvider
   
   auth = GitHubProvider(client_id="...", client_secret="...")
   mcp = FastMCP("SecureApp", auth=auth)
   ```
3. **Client authenticates** automatically via OAuth flow

### Testing a Server

1. **Use in-process testing**:
   ```python
   from fastmcp import Client
   from fastmcp.utilities.tests import run_server_async
   
   async with run_server_async(server) as url:
       async with Client(url) as client:
           result = await client.call_tool("tool_name", {})
   ```

2. **Or use CLI**: `fastmcp call server.py tool_name`

## Common Gotchas

- **Decorated functions are still callable**: In v3, `@mcp.tool` returns the original function, not a tool object. You can call it directly for testing.
- **STDIO servers don't stay running**: Each client spawns a new process. Use HTTP for persistent servers.
- **Tool names must be valid identifiers**: FastMCP validates tool names at registration (SEP-986). Avoid special characters.
- **Context injection requires async functions**: Sync functions can't receive `Context`. Use `async def` or inject via `Depends()`.
- **Resource URIs are case-sensitive**: `resource://docs/readme` and `resource://docs/README` are different.
- **OAuth requires browser interaction**: OAuth flows open the user's browser. Use bearer tokens for headless/server-to-server auth.
- **Mounted servers get namespaced**: When mounting a server with `mcp.mount(other_server, namespace="prefix")`, all components get prefixed.
- **Transforms modify components in-flight**: Transforms (namespace, visibility, tool transformation) don't modify source code—they reshape components as they flow to clients.
- **Task execution requires pydocket**: Background tasks (`task=True`) require `fastmcp[tasks]` extra. In-memory backend works out-of-the-box.
- **Proxy servers can't execute tasks**: Task execution is forbidden through proxy servers for security.

## Verification Checklist

Before submitting work with FastMCP:

- [ ] Server runs without errors: `fastmcp run server.py`
- [ ] All tools/resources/prompts are discoverable: `fastmcp list server.py`
- [ ] Tools execute correctly: `fastmcp call server.py tool_name arg=value`
- [ ] Type hints are correct (Pydantic models for complex args)
- [ ] Docstrings are present (used as tool descriptions)
- [ ] Authentication is configured if needed
- [ ] HTTP transport works if deploying remotely: `fastmcp run server.py --transport http --port 8000`
- [ ] Client can connect and call tools (test with `Client` class)
- [ ] Middleware/transforms are applied in correct order
- [ ] Error handling is in place (tools should not crash server)
- [ ] Logging is configured for production
- [ ] Configuration file (fastmcp.json) is valid JSON

## Resources

**Comprehensive navigation**: https://gofastmcp.com/llms.txt

**Critical documentation pages**:
1. [Getting Started](https://gofastmcp.com/getting-started/welcome) — Overview and first steps
2. [Servers](https://gofastmcp.com/servers/server) — Building MCP servers with decorators
3. [Clients](https://gofastmcp.com/clients/client) — Programmatic client API
4. [Deployment](https://gofastmcp.com/deployment/running-server) — Running and deploying servers
5. [Authentication](https://gofastmcp.com/servers/auth/authentication) — Securing servers
6. [Providers](https://gofastmcp.com/servers/providers/overview) — Sourcing components dynamically
7. [Transforms](https://gofastmcp.com/servers/transforms/transforms) — Modifying components in-flight

---

> For additional documentation and navigation, see: https://gofastmcp.com/llms.txt