---

name: mcp-server-integration description: "Connect mcp-agent applications to MCP servers and expose MCPApp workflows as FastMCP servers." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

MCP Server Integration

Use this sub-skill when an agent needs to connect an mcp-agent app to upstream MCP servers or expose an MCPApp itself as an MCP server. It covers transport configuration, server registry behavior, connection lifecycle, MCP primitives, OAuth/authentication, roots, sampling, elicitation, and safe client-install preparation.

Start Here

1. For app and agent construction, first read ../core-sdk/SKILL.md, then return here for server wiring.
2. Choose the direction:
   • Consume upstream MCP servers: configure mcp.servers, attach agents with server_names, or use gen_client/MCPAggregator directly.
   • Expose this app as an MCP server: decorate tools/workflows on MCPApp, then call create_mcp_server_for_app(app, **kwargs).
   • Prepare client installation/deployment: use the checks here, then follow ../cli-cloud-operations/SKILL.md for CLI install/deploy commands.
3. Read the closest bundled reference:
   • references/configuration.md for MCPServerSettings, transports, roots, registry, and client install dry-runs.
   • references/server-and-client-workflows.md for create_mcp_server_for_app, workflow tools, decorators, primitives, aggregators, sampling, and elicitation.
   • references/oauth-and-auth.md for downstream OAuth servers, token storage, pre-authorization, and OAuth-protected app servers.
   • references/troubleshooting.md for common failure modes and fixes.
4. Use bundled scripts before running real services:
   • scripts/validate_server_config.py --help
   • scripts/validate_server_config.py path/to/mcp_agent.config.yaml --check-executables
   • scripts/minimal_app_server.py --help
   • scripts/minimal_app_server.py --mode dry-run --json

Upstream Server Checklist

• Define every upstream server under mcp.servers.<server_name> and make sure the agent/workflow uses the same exact server_name.
• Use transport: stdio with command and args; use sse, streamable_http, or websocket with url.
• Put bearer/API tokens in headers or secrets-backed placeholders; use auth.oauth only for delegated OAuth flows.
• Set roots as file:// URIs when a server needs declared filesystem access, and include server_uri_alias only when the server expects a different mounted URI.
• Use allowed_tools to restrict high-risk or collision-prone tool surfaces before exposing them to an LLM.
• Prefer gen_client(server_name, app.context.server_registry, context=app.context) for a direct client session and MCPAggregator([...]) when an agent needs a combined tools/resources/prompts surface.

App Server Checklist

• Register simple callable tools with @app.tool for synchronous results and @app.async_tool when callers should receive workflow_id/run_id and poll later.
• Register workflow classes with @app.workflow and @app.workflow_run when the workflow needs explicit workflow semantics or signals.
• Wrap the running app with create_mcp_server_for_app(agent_app, **fastmcp_kwargs) only after async with app.run() as agent_app.
• Expect generic workflow tools: workflows-list, workflows-runs-list, workflows-run, workflows-get_status, workflows-resume, workflows-cancel, and workflows-store-credentials.
• For explicit workflow classes, expect per-workflow tools named workflows-<WorkflowName>-run; decorator tools expose their declared names instead.
• Avoid starting public network transports during validation; use scripts/minimal_app_server.py --mode dry-run to inspect the expected surface first.

MCP Primitives

• Tools: call with agent.call_tool(...), session.call_tool(...), or let an attached LLM invoke allowed tools.
• Resources: list/read with list_resources() and read_resource(uri).
• Prompts: list/get with list_prompts() and get_prompt(...); use agent prompt helpers when combining prompts with resource content.
• Roots: configure roots on the server entry; validate every URI starts with file://.
• Sampling: provide an MCPApp human-input callback when nested servers may request LLM sampling approval.
• Elicitation: provide an MCPApp elicitation callback when servers may call elicitation/create; schema fields must stay primitive (str, int, float, bool).

When Not To Use This Sub-skill

• Use ../core-sdk/SKILL.md for basic MCPApp, Agent, LLM, and workflow construction before server integration.
• Use ../durable-execution/SKILL.md for Temporal worker operations and durable workflow runtime management.
• Use ../cli-cloud-operations/SKILL.md for CLI command syntax, cloud deployment, and hosted app lifecycle operations.