Feature Request: MCP Server Definitions in agent.yaml

[chr1syy]

Feature Request: MCP Server Definitions in agent.yaml

Summary

Add an mcp_servers field to agent.yaml that allows defining MCP (Model Context Protocol) servers once and exporting them to each provider's native configuration format.

Problem

Currently, if I want to use the same MCP servers (e.g., a memory layer, database connector, or custom tool server) across multiple AI coding tools (Claude Code, Codex, OpenCode, Cursor, etc.), I need to:

1. Manually configure each tool's native format (.mcp.json, settings.json, etc.)
2. Keep these configurations in sync across projects
3. Duplicate effort when onboarding new projects or switching tools

MCP server support would extend GitAgent's "define once, use everywhere" philosophy to infrastructure integrations as well.

Proposed Solution

Add an mcp_servers section to agent.yaml:

# agent.yaml
name: my-agent
version: 1.0.0
description: Agent with shared MCP servers

mcp_servers:
  # SSE transport (remote servers)
  - name: memory
    transport: sse
    url: https://mcp.mem0.ai/sse
    env:
      MEM0_API_KEY: ${MEM0_API_KEY}
    description: Long-term memory layer for cross-session context

  # Stdio transport (local servers)
  - name: postgres
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      POSTGRES_URL: ${DATABASE_URL}
    description: Database access for queries

  # Filesystem access
  - name: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]

Export Behavior

Each adapter translates mcp_servers to the target platform's native format:

Claude Code (gitagent export --format claude-code):

// .mcp.json
{
  "mcpServers": {
    "memory": {
      "type": "sse",
      "url": "https://mcp.mem0.ai/sse",
      "env": {
        "MEM0_API_KEY": "${MEM0_API_KEY}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "${DATABASE_URL}"
      }
    }
  }
}

Other adapters: Generate equivalent configuration for Codex, OpenCode, Cursor, etc. (where MCP is supported) or document that MCP isn't available for that target.

Use Cases

1. Shared Memory Layer

Define a memory server (mem0, Zep, custom) once. Every agent that extends this base gets memory access regardless of which AI tool runs it.

# base-agent/agent.yaml
mcp_servers:
  - name: memory
    transport: sse
    url: https://mcp.mem0.ai/sse
    env:
      MEM0_API_KEY: ${MEM0_API_KEY}

# project-agent/agent.yaml
extends: https://github.com/org/base-agent.git
# Inherits memory MCP server automatically

2. Database Access

Teams can define database connections in a shared agent, ensuring consistent access patterns.

3. Custom Tool Servers

Internal tools exposed via MCP can be defined once and used across all projects.

Schema Proposal

mcp_servers:
  type: array
  items:
    type: object
    required: [name, transport]
    properties:
      name:
        type: string
        description: Identifier for this MCP server
      transport:
        type: string
        enum: [stdio, sse]
      description:
        type: string
        description: Human-readable description
      # For stdio transport
      command:
        type: string
        description: Command to run
      args:
        type: array
        items:
          type: string
        description: Command arguments
      # For sse transport
      url:
        type: string
        format: uri
        description: SSE endpoint URL
      # Common
      env:
        type: object
        additionalProperties:
          type: string
        description: Environment variables (supports ${VAR} syntax for secrets)

Composition Behavior

When using extends::

• Child agent's mcp_servers are merged with parent's
• On name collision, child overrides parent (consistent with existing tool behavior)
• Allow mcp_servers: [] to explicitly clear inherited servers if needed

Adapter Implementation Notes

Adapter	MCP Support	Export Format
claude-code	Yes	.mcp.json or inline in settings
cursor	Yes	Similar to Claude Code
codex	TBD	Needs research
opencode	TBD	Needs research
crewai	No	Document as unsupported
langchain	No	Document as unsupported

For adapters where MCP isn't supported, either:

1. Skip mcp_servers silently with a warning
2. Attempt to translate to equivalent tool definitions where possible

Why This Matters

GitAgent's value proposition is "define once, use everywhere." MCP is becoming the standard protocol for extending AI coding tools with external capabilities. Without MCP server support, users still need to maintain parallel configurations across tools — exactly the problem GitAgent solves for agent identity and skills.

Adding mcp_servers would make GitAgent the single source of truth for:

• Agent identity (SOUL.md) ✅ exists
• Agent constraints (RULES.md) ✅ exists
• Agent capabilities (skills/, tools/) ✅ exists
• Agent integrations (mcp_servers) ❌ missing

Additional Context

• MCP Specification: https://modelcontextprotocol.io/
• Claude Code MCP docs: https://docs.anthropic.com/en/docs/claude-code/mcp
• This would enable portable "baseline agents" with shared infrastructure (memory, databases, custom tools) that work across any supported AI coding environment.