freshcrate
Home > MCP Servers > agents

agents

One .agents source of truth to sync MCP servers, skills, and instructions across Codex, Claude Code, Gemini CLI, Cursor, Copilot, and Antigravity.

typescript

Description

One .agents source of truth to sync MCP servers, skills, and instructions across Codex, Claude Code, Gemini CLI, Cursor, Copilot, and Antigravity.

README

agents

One config to rule them all.
Practical standard layer for multi-LLM development.

npm versiondownloadsnode versionlicense Quick Start · Integrations · Commands · FAQ

agents start

The Problem

Every AI coding tool wants its own config format:

Codex Claude Gemini Cursor Copilot Antigravity Windsurf OpenCode Junie
Config .codex/config.toml CLI commands .gemini/settings.json .cursor/mcp.json .vscode/mcp.json Global mcp.json Global mcp_config.json opencode.json .junie/mcp/mcp.json
Instructions AGENTS.md CLAUDE.md AGENTS.md .cursorrules — AGENTS.md AGENTS.md AGENTS.md AGENTS.md
Format TOML JSON (via CLI) JSON JSON JSON JSON JSON JSON JSON

Result: Duplicated configs, team drift, painful onboarding.

agents gives you one source of truth in .agents/ and syncs MCP servers, skills, and instructions to every tool automatically. For Claude Code, it keeps AGENTS.md canonical and generates a minimal root CLAUDE.md wrapper (@AGENTS.md) when the Claude integration is enabled.

Quick Start

# 1. Install
npm install -g @agents-dev/cli

# 2. Interactive setup — picks integrations, adds MCP servers, syncs everything
agents start

# 3. Re-sync whenever config changes
agents sync

That's it. Your .agents/agents.json is now the single source of truth.

Using agents in this repository

This repository uses @agents-dev/cli to keep MCP servers, skills, and instructions aligned across supported AI tools.

Quick commands

agents status
agents mcp add <url-or-name>
agents mcp test --runtime
agents sync
agents sync --check

One MCP setup for all tools

Add a server once in .agents/agents.json, then run agents sync to materialize it for enabled integrations.

References

Supported Integrations

Integration MCP Servers Skills Instructions How it syncs
Codex ✅ ✅ ✅ Writes .codex/config.toml
Claude Code ✅ ✅ ✅ Calls claude mcp add/remove CLI + manages root CLAUDE.md wrapper
Gemini CLI ✅ ✅ ✅ Writes .gemini/settings.json
Cursor ✅ ✅ ✅ Writes .cursor/mcp.json + CLI enable
Copilot ✅ ✅ ✅ Writes .vscode/mcp.json
Antigravity ✅ ✅ ✅ Writes to global user profile mcp.json
Windsurf ✅ ✅ ✅ Writes to global user profile ~/.codeium/windsurf/mcp_config.json + workspace .windsurf/skills
OpenCode ✅ ✅ ✅ Writes project opencode.json (mcp block)
Junie ✅ ✅ ✅ Writes .junie/mcp/mcp.json + skills bridge .junie/skills

Project Layout

your-project/
├── AGENTS.md                        ← Canonical instructions for all tools
├── CLAUDE.md                        ← Generated Claude wrapper (`@AGENTS.md`)
├── .agents/
│   ├── agents.json                  ← MCP servers & config (commit this)
│   ├── local.json                   ← Secrets & overrides (gitignored)
│   ├── skills/                      ← Reusable workflow definitions
│   │   └── my-skill/SKILL.md
│   └── generated/                   ← Auto-generated artifacts (gitignored)
│       ├── codex.config.toml
│       ├── gemini.settings.json
│       ├── cursor.mcp.json
│       ├── windsurf.mcp.json
│       ├── opencode.json
│       └── ...
│
│  ┌─── Generated by `agents sync` ───┐
├── .codex/config.toml                │  Materialized tool configs
├── .gemini/settings.json             │  (gitignored in source-only mode)
├── .cursor/mcp.json                  │
├── .vscode/mcp.json                  │
├── opencode.json                     │
├── .claude/skills/ → .agents/skills  │  Claude workspace bridges
├── .cursor/skills/ → .agents/skills  │
├── .gemini/skills/ → .agents/skills  │
└── .windsurf/skills/ → .agents/skills│

Git strategy: By default only .agents/agents.json, .agents/skills/, and AGENTS.md are committed. Generated CLAUDE.md and tool-specific outputs are gitignored in source-only mode and regenerated with agents sync.

Command Overview

Setup & Sync

Command Description
agents start Interactive setup wizard — integrations, MCP servers, skills, first sync
agents start --inject-docs Also upsert an agents guide block in README.md (+ CONTRIBUTING.md if present)
agents start --reinit Reinitialize existing .agents/agents.json with fresh wizard/default choices
agents init Scaffold .agents/ directory without guided setup
agents sync Regenerate and materialize all tool configs
agents sync --check Strict read-only drift check — exits 2 if config is out of sync
agents watch Auto-sync on .agents/ file changes (--once exits non-zero on sync failure)

Diagnostics

Command Description
agents status Show integrations, MCP servers, file states, and live probes
agents status --fast Skip external CLI probes for quicker output
agents doctor Validate configs, check for issues, suggest fixes
agents doctor --fix Auto-fix what can be fixed
agents update Check for newer CLI version on npm

MCP Server Management

Command Description
agents mcp add <name> Add a server interactively
agents mcp add <url> Import a server from URL (mcpservers.org, GitHub, etc.)
agents mcp import --file config.json Bulk import from JSON/JSONC file
agents mcp list List all configured servers
agents mcp remove <name> Remove a server (--no-sync skips auto-sync for add/import/remove)
agents mcp test Validate server definitions
agents mcp test --runtime Live connectivity check via tool CLIs

Integrations

Command Description
agents connect --llm cursor,claude Add integrations to the currently enabled set
agents disconnect --llm codex Disable integrations
agents reset Remove generated files, keep .agents/
agents reset --hard Full cleanup — removes all agents-managed setup

How It Works

┌──────────────────────────────────────────────────────────────┐
│                      agents sync                             │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   .agents/agents.json ─── merge ──→ Resolved    ──→ Codex   │
│         (shared)           ↑        Registry          TOML   │
│                            │           │                     │
│   .agents/local.json ──────┘           ├────────→ Claude     │
│      (secrets)                         │          CLI + root │
│                                        │          CLAUDE.md  │
│                                        ├────────→ Gemini     │
│   ${ENV_VARS} ─── resolve ─────────────┤          JSON       │
│   ${PROJECT_ROOT}                      ├────────→ Cursor     │
│                                        │          JSON + CLI │
│                                        ├────────→ Copilot    │
│                                        │          VS Code    │
│                                        ├────────→ Antigravity│
│                                        │          Global     │
│                                        ├────────→ Windsurf   │
│                                        │          Global MCP │
│                                        ├────────→ OpenCode   │
│                                        │          opencode.json │
│                                        └────────→ Junie      │
│                                                   .junie/mcp/ │
│                                                              │
│   .agents/skills/ ── symlink ──→ .claude/skills              │
│                                  .cursor/skills              │
│                                  .gemini/skills              │
│                                  .junie/skills               │
│                                  .windsurf/skills            │
└──────────────────────────────────────────────────────────────┘
  1. Load — reads .agents/agents.json + merges secrets from .agents/local.json
  2. Resolve — expands ${PROJECT_ROOT}, ${ENV_VAR} placeholders, filters by enabled and requiredEnv
  3. Route — sends each server to its target integrations (or all, if no targets specified)
  4. Generate — renders tool-specific config formats (TOML for Codex, JSON for others)
  5. Materialize — writes configs atomically (project-local and global targets), calls CLIs for Claude/Cursor, and manages Claude's root CLAUDE.md wrapper
  6. Bridge skills — creates symlinks from tool directories to .agents/skills/ (including Windsurf workspace bridge)

MCP Server Examples

Add from mcpservers.org

agents mcp add https://mcpservers.org/servers/context7-mcp

Add a stdio server

agents mcp add my-server \
  --command npx \
  --arg @my-org/mcp-server \
  --arg /path/to/project

Add an HTTP server with secrets

agents mcp add company-api \
  --url "https://api.company.com/mcp" \
  --secret-header "Authorization=Bearer {{API_TOKEN}}"

Secrets are automatically detected and split: placeholders go to agents.json (committed), real values to local.json (gitignored).

Target specific tools

# Only for Claude
agents mcp add claude-only-server --url "https://..." --target claude

# Only for Cursor and Copilot
agents mcp add ide-server --command ide-mcp --target cursor --target copilot_vscode

Security

What Where
🔓 Server definitions, team config .agents/agents.json — committed
🔒 API keys, tokens, secrets .agents/local.json — gitignored

How secrets work:

  • When you add a server, agents detects secret-like values (API keys, tokens, JWTs)
  • Secrets are moved to local.json and replaced with ${PLACEHOLDER} in agents.json
  • agents doctor warns if it finds literal secrets in committed config
  • All env keys and header names are validated to prevent injection

Team Workflow

Lead sets up the project:

agents start
agents mcp add https://mcpservers.org/servers/context7-mcp
agents mcp add company-api --url "https://api.company.com/mcp" \
  --secret-header "Authorization=Bearer {{API_TOKEN}}"
git add .agents/agents.json .agents/skills/ AGENTS.md && git commit -m "Add agents config"

New member onboards:

git clone <repo> && cd <repo>
agents start        # Preserves team config and syncs local tool files
# Add your local secrets in .agents/local.json if required by project MCP servers

One command. Same MCP servers, same skills, same instructions. No drift.

FAQ

Does this replace AGENTS.md?
No. It extends it. AGENTS.md is human-readable guidance for LLMs; agents handles machine-readable config (MCP servers, skills) and keeps everything in sync. When Claude integration is enabled, agents also generates a minimal root CLAUDE.md wrapper that references AGENTS.md.
Can I use this with only one tool?
Yes. You still get cleaner config management, safer git defaults, secret splitting, and easy MCP server management — even for a single tool.
Where should secrets live?
In .agents/local.json (gitignored by default). The CLI automatically splits secrets from public config when you add MCP servers.
What happens during agents sync?
It reads your .agents/ config, merges secrets, resolves placeholders, generates tool-specific files, and writes them atomically. For Claude and Cursor it also calls their CLIs to register servers. The whole process is idempotent and safe to run repeatedly. For Claude it also maintains a root CLAUDE.md wrapper without duplicating the contents of AGENTS.md.
How do I keep configs in sync automatically?
Run agents watch — it polls .agents/ files and auto-syncs on changes. Or run agents sync manually after editing config.
Can I target an MCP server to specific tools only?
Yes. Add "targets": ["claude", "cursor"] to a server definition in agents.json, or use the --target flag with agents mcp add. Servers without targets go to all enabled integrations.

Docs

Resource
📖 Usage Examples — solo dev, teams, monorepos, scripting
🏗️ System Architecture — sync internals, file formats, security model
📋 Changelog — version history and migration notes

Community

IssuesDiscussionsnpmRelease History

VersionChangesUrgencyDate
v0.8.7## Added - New integration: **Junie** (JetBrains) — MCP servers synced to `.junie/mcp/mcp.json`, skills bridged to `.junie/skills/`. ## Fixed - Fixed `agents sync` dropping `cwd` from generated MCP configs for all tools (Codex, Gemini, VS Code, Cursor, Copilot, Antigravity, Windsurf, OpenCode, Junie). Closes #11.Medium3/23/2026

Dependencies & License Audit

Loading dependencies...

Similar Packages

spaceship-mcp🚀 Manage domains, DNS, contacts, and listings with spaceship-mcp, a community-built MCP server for the Spaceship API.main@2026-04-21
website-design-systems-mcp🎨 Extract complete design systems from websites and generate AI-ready skill.md files to replicate exact design elements efficiently.main@2026-04-21
MCP-X-web🤖 Develop enterprise AI agents with integrated tools for chat, video, image editing, and secure multi-tenant workflows.main@2026-04-21
dev-workflows⚙️ Define and compile AI coding rules, commands, and templates into workflows that work across multiple editors and agents.main@2026-04-21
awesome-agent-skills-mcp🔧 Enhance agent skills with the Awesome Agent Skills MCP Server, providing powerful tools for managing and optimizing agent functionality.main@2026-04-21