Mcp Agent

---
name: mcp-agent
description: "Build, compose, serve, operate, and troubleshoot mcp-agent
  applications, workflows, MCP servers, Temporal workers, CLI/cloud deployments,
  and observability integrations."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# mcp-agent

Use this repo skill when a task involves the `mcp-agent` Python package or its CLIs: building MCP-enabled agents, composing effective workflow patterns, exposing applications as MCP servers, operating MCP Agent Cloud, using Temporal durability, or configuring logging/tracing/integrations.

## First Checks

1. Confirm the package is available with `python -c "import mcp_agent; print(mcp_agent.__name__)"` or install it with `pip install "mcp-agent"` / `uv add "mcp-agent"`.
2. Add optional extras only for the selected workflow: `mcp-agent[openai]`, `[anthropic]`, `[google]`, `[azure]`, `[bedrock]`, `[cohere]`, `[temporal]`, `[langchain]`, `[crewai]`, or `[redis]`.
3. Keep secrets in `mcp_agent.secrets.yaml`, environment variables, or deployment secret handles; keep reusable defaults in `mcp_agent.config.yaml` or a `Settings` object.
4. Read `references/repo-provenance.md` before deciding whether this skill matches a checkout or whether `refresh-repo-skill` is needed.
5. Read `references/troubleshooting.md` for cross-cutting install, import, config, optional dependency, CLI, and service failures.

## Route by Task

- **Core SDK and app code:** use `sub-skills/core-sdk/SKILL.md` for `MCPApp`, `Agent`, `AgentSpec`, `AugmentedLLM`, `RequestParams`, settings, secrets, local function tools, decorators, and factory basics.
- **Workflow composition:** use `sub-skills/workflow-patterns/SKILL.md` for routers, intent classifiers, parallel fan-out/fan-in, orchestrators, deep orchestrators, evaluator-optimizer loops, swarms, and structured outputs.
- **MCP server integration:** use `sub-skills/mcp-server-integration/SKILL.md` for upstream MCP server config, transports, roots, sampling, elicitation, OAuth/auth, `create_mcp_server_for_app`, and app-as-server validation.
- **CLI and Cloud operations:** use `sub-skills/cli-cloud-operations/SKILL.md` for `mcp-agent`, `mcp-cloud`, `mcpc`, project scaffolding, diagnostics, local dev commands, deploy, logs, env/secrets, workflows, and client install.
- **Durable execution:** use `sub-skills/durable-execution/SKILL.md` when workflows need Temporal workers, long-running tools, pause/resume, signals, retry policies, activity registration, or service-backed durability.
- **Observability and integrations:** use `sub-skills/observability-integrations/SKILL.md` for logger transports, OpenTelemetry, token accounting, progress/streaming, provider extras, LM Studio/local endpoints, LangChain, and CrewAI adapters.

## Common Decision Points

- Start with `core-sdk` when the user asks to create or debug Python application code; route to `workflow-patterns` only after the app/agent basics are clear.
- Route to `mcp-server-integration` when the words are about MCP transports, server config, app-as-server behavior, OAuth, resources, prompts, sampling, roots, elicitation, or client/server tool surfaces.
- Route to `cli-cloud-operations` when the task is command syntax, scaffolding, config checks, deployments, logs, hosted app state, environment secrets, or installing a server into Claude Code/Cursor/VS Code/ChatGPT clients.
- Route to `durable-execution` when the user already has or wants a workflow that must survive restarts, pause for human input, receive signals, or run in a Temporal worker.
- Route to `observability-integrations` when failures involve provider wrapper imports, OpenTelemetry exporters, token counters, JSONL event logs, streaming events, local model endpoints, or LangChain/CrewAI adapters.

## Safe Validation Helpers

- `sub-skills/core-sdk/scripts/check_core_sdk.py` checks imports, signatures, local tools, decorators, `AgentSpec`, and `RequestParams` without credentials or network.
- `sub-skills/workflow-patterns/scripts/check_workflow_imports.py` verifies canonical workflow imports and class names such as `LLMRouter`.
- `sub-skills/mcp-server-integration/scripts/validate_server_config.py` checks MCP server config shape and optional executable availability.
- `sub-skills/cli-cloud-operations/scripts/collect_cli_help.py` collects safe `--help` snapshots without deploy/login/install side effects.
- `sub-skills/durable-execution/scripts/check_temporal_config.py` validates Temporal config statically without starting a worker.
- `sub-skills/observability-integrations/scripts/check_observability_config.py` and `sub-skills/observability-integrations/scripts/summarize_event_log.py` inspect logger/OTEL config and JSONL event logs safely.

## Safety Notes

- Do not run Cloud deployment, client install writes, env secret mutation, workflow resume/cancel, or public server transports unless the user explicitly intends mutation.
- Do not assume optional provider SDKs, Temporal, Redis, LangChain, CrewAI, or cloud credentials are present in a base install; install and validate the smallest extra needed.
- Do not paste API keys or secret handles into generated code, logs, support transcripts, or client snippets.
- Prefer read-only `--help`, config validation, bundled checker scripts, import checks, and dry-run/static modes before starting services or calling external providers.