---
name: fastmcp-service-workflow
description: Maintain existing uv-managed FastMCP servers, including transport and lifespan behavior, tool/resource/prompt curation, authorization and input boundaries, client integration tests, generated-surface review, and upgrade diagnostics.
license: Apache-2.0
compatibility: Designed for Codex and compatible Agent Skills clients maintaining FastMCP servers on macOS with uv, the installed FastMCP version, and the repository's existing transport and deployment tools.
metadata:
  owner: gaelic-ghost
  repo: python-skills
  category: python-fastmcp
allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(uv:*)
---

# FastMCP Service Workflow

## Purpose

Maintain a curated FastMCP server as an application surface, not a mechanical
mirror of HTTP routes. Keep tool, resource, and prompt design user-oriented;
make transport, authentication, authorization, lifespan, and side-effect
boundaries explicit.

## Workflow

1. Inspect the installed FastMCP version, `pyproject.toml`, server entrypoint,
   component definitions, transport, lifespan, auth configuration, tests, and
   deployment configuration before changing behavior.
2. Classify each public capability:
   - a tool for an action or bounded computation;
   - a resource or template for read-oriented data;
   - a prompt for a reusable message workflow.
3. Keep implementation logic in existing typed domain boundaries. Do not expose
   transport-centric route names, broad autogenerated APIs, secrets, or raw
   infrastructure controls as MCP capabilities.
4. Choose transport deliberately. STDIO clients own the server process and its
   environment; HTTP is the normal production transport. Make every required
   configuration value explicit for the selected transport.
5. Define authorization at the component or server boundary when the HTTP
   deployment needs it. Do not infer identity or permissions from a model's
   request, and do not claim HTTP OAuth checks protect STDIO transport.
6. Treat `FastMCP.from_fastapi(...)` and OpenAPI imports as review inputs.
   Curate names, parameter shapes, errors, and capability boundaries before
   keeping generated output as a public server surface.
7. Test through an in-memory FastMCP client first, then add transport and auth
   integration tests only where those are part of the deployment contract.
8. Run the repository's configured checks and report any untested transport,
   authorization, or external-write boundary separately.

## Version And Documentation Discipline

Use the installed FastMCP version and its release notes for implementation
decisions. The public FastMCP documentation tracks `main` and can describe
unreleased behavior. Use a host-provided `fastmcp_docs` tool only when one is
already configured; this plugin does not package it.

## Handoffs

- New MCP scaffold: `bootstrap-python-mcp-service`.
- FastAPI/FastMCP coexistence or mounting: `integrate-fastapi-fastmcp`.
- FastAPI service maintenance: `fastapi-service-workflow`.
- Generic testing, package, CI, tooling, and upgrade work: the corresponding
  Python workflows.

## Output Shape

Return the component and transport boundary changed, installed FastMCP version,
authorization effect, test commands and results, deployment-readiness effect,
and residual risk.

## Guardrails

- Do not add a generated route mirror as a long-term MCP API without curation.
- Do not expose write-capable tools without explicit authorization, input,
  timeout, idempotency, and approval behavior.
- Do not run a production transport, deploy a server, or execute live writes
  only to validate the skill.

## References

- [FastMCP client testing](https://gofastmcp.com/servers/testing)
- [FastMCP transports](https://gofastmcp.com/clients/transports)
- [FastMCP authorization](https://gofastmcp.com/servers/authorization)
- [FastMCP CLI](https://gofastmcp.com/cli/overview)