| name | animus-mcp-servers-for-agents |
| description | Connect agents to Context7, package-version, sequential-thinking, memory, GitHub MCP servers |
| user_invocable | false |
| auto_invoke | true |
| animus_version | 0.7.0-rc.18 |
MCP Servers for Animus Agents
Animus agents can connect to external MCP servers beyond the built-in animus server. This gives agents access to documentation lookup, package version checking, structured reasoning, persistent memory, and GitHub operations.
Configuring MCP Servers
1. Define servers under the top-level mcp_servers: key
Servers go in .animus/workflows.yaml or any .animus/workflows/*.yaml file:
mcp_servers:
context7:
command: npx
args: ["-y", "@upstash/context7-mcp"]
package-version:
command: npx
args: ["-y", "mcp-package-version"]
sequential-thinking:
command: npx
args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]
memory:
command: npx
args: ["-y", "@modelcontextprotocol/server-memory"]
github:
transport: http
url: https://api.githubcopilot.com/mcp/
oauth:
flow: manual_bearer
bearer_env: GITHUB_MCP_TOKEN
(The @modelcontextprotocol/server-github npm package is deprecated
upstream — use GitHub's hosted MCP endpoint, as the OAuth example later in
this skill does.)
Each entry picks exactly one transport via transport::
stdio (default when omitted) — requires command:; optional args: and env:. url must not be set.http — requires url: (an http:// or https:// endpoint). command, args, and env must not be set.
mcp_servers:
my-remote:
transport: http
url: https://mcp.example.com/mcp
Optional per-server fields: config: (arbitrary key-value config passed to the server) and tools: (declared tool-name list — schema-validated but not currently enforced as a runtime filter, so don't rely on it to restrict access).
Secrets in env: blocks: use ${VAR} interpolation (${VAR:-default}, ${VAR:?error}) rather than literal values. Resolution checks the process environment first, then OS keychain entries set via animus secret set <KEY> (preferred for credentials).
2. Bind servers to agent profiles
agents:
implementer:
mcp_servers: ["animus", "context7"]
researcher:
mcp_servers: ["animus", "context7", "package-version", "memory"]
reviewer:
mcp_servers: ["animus", "github", "sequential-thinking"]
Agents only get access to the servers listed in their mcp_servers array.
How servers reach the provider
The resolved server set is passed down to the provider plugins themselves:
it rides the provider contract for animus agent run and animus chat to
any provider plugin that declares supports_mcp (manifest field, plugin
protocol 1.2.0; undeclared defaults true), and on the workflow path via
workflow-runner v0.4.3+. Secret-bearing servers (all OAuth flows) are
rewritten to animus-mcp-proxy stdio entries before pass-down — tokens
never reach CLI configs or argv. The name animus always resolves to the
built-in animus mcp serve stdio surface.
For deterministic, LLM-free access from scripts and command phases, use
animus mcp tools <server> (list) and
animus mcp call <server> <tool> --args '<json>' (v0.7.0-rc.9+) — OAuth
servers route through the proxy with the bearer injected, never printed.
3. Reference tools in agent prompts
Tell agents what tools are available and when to use them:
implementer:
system_prompt: |
TOOLS: You have access to context7 MCP tools. Before writing code
that uses external libraries, use resolve-library-id and
get-library-docs to look up the CURRENT API.
OAuth-Protected HTTP Servers
http servers can carry an oauth: block. Flows: authorization_code (interactive browser login via animus mcp auth <server>), client_credentials, refresh_token, manual_bearer. Credential material is read from env vars via *_env fields (client_id_env, client_secret_env, refresh_token_env, bearer_env), never from YAML. Other fields: token_url, scopes, audience, cache (default true), and — for authorization_code providers without Dynamic Client Registration — a pre-registered client_id plus client_secret_env for confidential clients (v0.7.0-rc.12+; resolved from process env, then the animus secret keychain).
mcp_servers:
github:
transport: http
url: https://api.githubcopilot.com/mcp/
oauth:
flow: authorization_code
scopes: [repo, read:user]
CLI: animus mcp auth <server> (login), animus mcp auth-status, animus mcp auth-logout <server>. Full shape and validation rules: docs/reference/mcp-oauth.md in animus-cli.
Phase-Level Bindings
Top-level phase_mcp_bindings attaches servers to specific phases (mainly used by pack overlays):
phase_mcp_bindings:
research:
servers: [context7]
Server names must resolve against the mcp_servers: map. See the pack-authoring docs for how packs ship these.
Skills are a third attachment path (v0.5.14): a skill definition can declare mcp_servers, and when a workflow phase's skills: (or the executing agent profile's skills:) resolve and apply, the skill's declared servers join the phase contract the same way phase_mcp_bindings do — resolved by name against the mcp_servers: map; unknown names warn and are skipped.
Per-Run Wiring (CLI)
animus agent run and animus chat send resolve the server set as: the
--agent profile's mcp_servers ∪ the --skill's mcp_servers ∪
--mcp-server <name> additions (repeatable; the name must exist in the
project's mcp_servers map, or animus for the built-in surface), minus the
built-in animus server when --no-animus-mcp is passed. When no profile or
skill names any server, the baseline set is just the built-in animus server.
A tool whose CLI cannot speak MCP receives no MCP wiring.
Recommended Servers
Context7 (@upstash/context7-mcp) — HIGH priority
Up-to-date, version-specific library documentation. Prevents hallucinated APIs.
Tools: resolve-library-id, get-library-docs
Best for: implementer, architect, docs-writer, researcher
Why: LLM training data goes stale. React Router 7, Hono, Drizzle, and Better-Auth all move fast. Context7 gives agents current docs instead of guessing.
Package Version Check (mcp-package-version) — MEDIUM priority
Checks latest stable versions from npm registry.
Tools: Check npm/PyPI/Maven/Go versions, bulk check multiple packages.
Best for: researcher, auditor
Why: Prevents agents from adding outdated dependency versions.
Sequential Thinking (@modelcontextprotocol/server-sequential-thinking) — MEDIUM priority
Helps agents break down complex problems step by step.
Best for: architect (dependency graphs), product-owner (feature evaluation), reviewer (code review), auditor (security analysis)
Why: Complex reasoning tasks benefit from structured step-by-step thinking.
Memory (@modelcontextprotocol/server-memory) — MEDIUM priority
Persistent memory across agent runs. Agents can remember what they reviewed last time.
Best for: planner, researcher, scanner, product-owner, architect, reconciler
Why: Without memory, each cron run starts from scratch. The PO can't remember what it reviewed, the researcher re-checks the same packages, the reconciler re-analyzes the same tasks.
GitHub (@modelcontextprotocol/server-github) — LOW priority
Structured GitHub operations as MCP tools.
Best for: planner, reviewer, reconciler
Why: Mostly redundant with gh CLI (already in tools_allowlist). Useful for structured PR data (reviews, checks, mergeable status) without parsing CLI output.
Skipped Servers
- Filesystem MCP — redundant with Claude Code's native Read/Write/Glob/Grep
- Fetch MCP — redundant with WebFetch already in tools_allowlist
- Rust-docs MCP — only useful for Rust projects
- SonarQube MCP — requires external infrastructure
Agent ↔ Server Matrix
animus ctx7 pkg-ver seq-think memory github
planner x x x
implementer x x
reviewer x x x
researcher x x x x
scanner x x
product-owner x x x
architect x x x x
auditor x x x
docs-writer x x
reconciler x x x
devops x
Tools Allowlist
MCP server tools are separate from the tools_allowlist. The allowlist controls which shell programs command phases can invoke. MCP tools are controlled per-agent via the mcp_servers binding.
To enable web search for agents, add to tools_allowlist:
tools_allowlist:
- WebSearch
- WebFetch
