feat: add mcp_servers field to agent.yaml for portable MCP server definitions

Define MCP servers once in agent.yaml and export to each provider's native
format. Supports both stdio-based (command + args) and HTTP-based (url) servers.

Tier 1 adapters (native MCP config): Claude Code (.mcp.json), Cursor
(.cursor/mcp.json), Gemini (.gemini/settings.json), Codex (codex.json),
OpenCode (opencode.json).

Tier 2 adapters (markdown docs): system-prompt, copilot, openai, crewai,
lyzr, nanobot, openclaw.

Also fixes pre-existing duplicate .requiredOption bugs in export and import
commands, and fixes codex case placed after default in export switch.

Closes #57

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: chr1syy

examples/full/agent.yaml

@@ -132,6 +132,18 @@ compliance:
         required_roles: [analyst, reviewer]
         approval_required: true
     enforcement: strict
+mcp_servers:
+  regulatory-db:
+    command: npx
+    args:
+      - "-y"
+      - "@compliance/mcp-regulatory-search"
+    env:
+      REG_DB_URL: "${REG_DB_URL}"
+  compliance-api:
+    url: "https://compliance-api.internal/mcp"
+    headers:
+      Authorization: "Bearer ${COMPLIANCE_API_TOKEN}"
 tags:
   - compliance
   - financial-services

spec/schemas/agent-yaml.schema.json

@@ -228,6 +228,13 @@
       "items": { "type": "string" },
       "uniqueItems": true
     },
+    "mcp_servers": {
+      "type": "object",
+      "description": "MCP server definitions. Keys are server names. Each server is either stdio-based (command) or HTTP-based (url).",
+      "additionalProperties": {
+        "$ref": "#/$defs/mcp_server_config"
+      }
+    },
     "metadata": {
       "type": "object",
       "description": "Arbitrary key-value metadata. Values must be strings, numbers, or booleans.",
@@ -243,6 +250,42 @@
   "additionalProperties": false,
 
   "$defs": {
+    "mcp_server_config": {
+      "type": "object",
+      "description": "Configuration for a single MCP server (stdio or HTTP)",
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Executable command for stdio-based servers"
+        },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Arguments for the command"
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Environment variables. Use ${VAR} for interpolation."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL for HTTP-based (SSE/streamable HTTP) MCP servers"
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "HTTP headers for URL-based servers"
+        }
+      },
+      "oneOf": [
+        { "required": ["command"] },
+        { "required": ["url"] }
+      ],
+      "additionalProperties": false
+    },
+
     "dependency": {
       "type": "object",
       "required": ["name", "source"],

src/adapters/claude-code.ts

@@ -3,11 +3,56 @@ import { join, resolve } from 'node:path';
 import yaml from 'js-yaml';
 import { loadAgentManifest, loadFileIfExists } from '../utils/loader.js';
 import { loadAllSkillMetadata } from '../utils/skill-loader.js';
+import { buildMcpServersConfig } from './shared.js';
 
-export function exportToClaudeCode(dir: string): string {
+/**
+ * Export a gitagent to Claude Code format.
+ *
+ * Claude Code uses:
+ *   - CLAUDE.md      (custom agent instructions, project root)
+ *   - .mcp.json      (MCP server configuration)
+ */
+export interface ClaudeCodeExport {
+  /** Content for CLAUDE.md */
+  instructions: string;
+  /** Content for .mcp.json (null if no MCP servers defined) */
+  mcpConfig: Record<string, unknown> | null;
+}
+
+export function exportToClaudeCode(dir: string): ClaudeCodeExport {
   const agentDir = resolve(dir);
   const manifest = loadAgentManifest(agentDir);
 
+  const instructions = buildInstructions(agentDir, manifest);
+  const mcpServers = buildMcpServersConfig(manifest.mcp_servers);
+  const mcpConfig = mcpServers ? { mcpServers } : null;
+
+  return { instructions, mcpConfig };
+}
+
+/**
+ * Export as a single string (for `gitagent export -f claude-code`).
+ */
+export function exportToClaudeCodeString(dir: string): string {
+  const exp = exportToClaudeCode(dir);
+  const parts: string[] = [];
+
+  parts.push('# === CLAUDE.md ===');
+  parts.push(exp.instructions);
+
+  if (exp.mcpConfig) {
+    parts.push('\n# === .mcp.json ===');
+    parts.push(JSON.stringify(exp.mcpConfig, null, 2));
+  }
+
+  return parts.join('\n');
+}
+
+function buildInstructions(
+  agentDir: string,
+  manifest: ReturnType<typeof loadAgentManifest>,
+): string {
+
   // Build CLAUDE.md content
   const parts: string[] = [];
 

src/adapters/codex.ts

@@ -3,7 +3,7 @@ import { join, resolve } from 'node:path';
 import yaml from 'js-yaml';
 import { loadAgentManifest, loadFileIfExists } from '../utils/loader.js';
 import { loadAllSkills, getAllowedTools } from '../utils/skill-loader.js';
-import { buildComplianceSection } from './shared.js';
+import { buildComplianceSection, buildMcpServersConfig } from './shared.js';
 
 /**
  * Export a gitagent to OpenAI Codex CLI format.
@@ -185,6 +185,12 @@ function buildConfig(manifest: ReturnType<typeof loadAgentManifest>): Record<str
     }
   }
 
+  // MCP servers
+  const mcpServers = buildMcpServersConfig(manifest.mcp_servers);
+  if (mcpServers) {
+    config.mcpServers = mcpServers;
+  }
+
   return config;
 }
 

src/adapters/copilot.ts

@@ -3,7 +3,7 @@ import { join, resolve } from 'node:path';
 import yaml from 'js-yaml';
 import { loadAgentManifest, loadFileIfExists } from '../utils/loader.js';
 import { loadAllSkills, getAllowedTools } from '../utils/skill-loader.js';
-import { buildComplianceSection } from './shared.js';
+import { buildComplianceSection, buildMcpServersMarkdown } from './shared.js';
 
 /**
  * Export a gitagent to GitHub Copilot CLI format.
@@ -145,6 +145,12 @@ function buildAgentMd(
     }
   }
 
+  // MCP servers
+  const mcpSection = buildMcpServersMarkdown(manifest.mcp_servers);
+  if (mcpSection) {
+    parts.push(mcpSection);
+  }
+
   // Compliance constraints
   if (manifest.compliance) {
     const constraints = buildComplianceSection(manifest.compliance);

src/adapters/crewai.ts

@@ -3,6 +3,7 @@ import { join, resolve } from 'node:path';
 import yaml from 'js-yaml';
 import { loadAgentManifest, loadFileIfExists } from '../utils/loader.js';
 import { loadAllSkills } from '../utils/skill-loader.js';
+import { buildMcpServersMarkdown } from './shared.js';
 
 export function exportToCrewAI(dir: string): string {
   const agentDir = resolve(dir);
@@ -32,6 +33,12 @@ export function exportToCrewAI(dir: string): string {
     backstory += `\n\nCapabilities (Skills):\n${skillDescriptions}`;
   }
 
+  // MCP servers
+  const mcpSection = buildMcpServersMarkdown(manifest.mcp_servers);
+  if (mcpSection) {
+    backstory += `\n\n${mcpSection}`;
+  }
+
   // Build CrewAI YAML config
   const crewConfig: Record<string, unknown> = {
     agents: {

src/adapters/cursor.ts

@@ -3,6 +3,7 @@ import { join, resolve, basename } from 'node:path';
 import yaml from 'js-yaml';
 import { loadAgentManifest, loadFileIfExists } from '../utils/loader.js';
 import { loadAllSkills, getAllowedTools } from '../utils/skill-loader.js';
+import { buildMcpServersConfig } from './shared.js';
 
 /**
  * Export a gitagent to Cursor rules format.
@@ -28,6 +29,8 @@ export interface CursorRule {
 
 export interface CursorExport {
   rules: CursorRule[];
+  /** Content for .cursor/mcp.json (null if no MCP servers defined) */
+  mcpConfig: Record<string, unknown> | null;
 }
 
 export function exportToCursor(dir: string): CursorExport {
@@ -49,7 +52,11 @@ export function exportToCursor(dir: string): CursorExport {
     rules.push(buildSkillRule(skill));
   }
 
-  return { rules };
+  // MCP servers
+  const mcpServers = buildMcpServersConfig(manifest.mcp_servers);
+  const mcpConfig = mcpServers ? { mcpServers } : null;
+
+  return { rules, mcpConfig };
 }
 
 /**
@@ -66,6 +73,12 @@ export function exportToCursorString(dir: string): string {
     parts.push('');
   }
 
+  if (exp.mcpConfig) {
+    parts.push('# === .cursor/mcp.json ===');
+    parts.push(JSON.stringify(exp.mcpConfig, null, 2));
+    parts.push('');
+  }
+
   return parts.join('\n').trimEnd() + '\n';
 }
 

src/adapters/gemini.ts

@@ -3,7 +3,7 @@ import { join, resolve } from 'node:path';
 import yaml from 'js-yaml';
 import { loadAgentManifest, loadFileIfExists } from '../utils/loader.js';
 import { loadAllSkills, getAllowedTools } from '../utils/skill-loader.js';
-import { buildComplianceSection } from './shared.js';
+import { buildComplianceSection, buildMcpServersConfig } from './shared.js';
 
 /**
  * Export a gitagent to Google Gemini CLI format.
@@ -244,8 +244,9 @@ function buildSettings(
     settings.hooks = hooksConfig;
   }
 
-  // MCP servers (placeholder - requires manual configuration)
-  settings.mcpServers = {};
+  // MCP servers
+  const mcpServers = buildMcpServersConfig(manifest.mcp_servers);
+  settings.mcpServers = mcpServers ?? {};
 
   return settings;
 }

src/adapters/index.ts

@@ -1,5 +1,5 @@
 export { exportToSystemPrompt } from './system-prompt.js';
-export { exportToClaudeCode } from './claude-code.js';
+export { exportToClaudeCode, exportToClaudeCodeString } from './claude-code.js';
 export { exportToOpenAI } from './openai.js';
 export { exportToCrewAI } from './crewai.js';
 export { exportToOpenClawString, exportToOpenClaw } from './openclaw.js';

src/adapters/lyzr.ts

@@ -1,6 +1,7 @@
 import { resolve, join } from 'node:path';
 import { loadAgentManifest, loadFileIfExists } from '../utils/loader.js';
 import { loadAllSkills, getAllowedTools } from '../utils/skill-loader.js';
+import { buildMcpServersMarkdown } from './shared.js';
 
 export interface LyzrAgentPayload {
   name: string;
@@ -66,6 +67,10 @@ function buildAgentInstructions(agentDir: string): string {
     parts.push(`## Skill: ${skill.frontmatter.name}\n${skill.frontmatter.description}${toolsNote}\n\n${skill.instructions}`);
   }
 
+  // MCP servers
+  const mcpSection = buildMcpServersMarkdown(manifest.mcp_servers);
+  if (mcpSection) parts.push(mcpSection);
+
   // Compliance constraints
   if (manifest.compliance) {
     const c = manifest.compliance;