Skip to main content
ACE3 LogoACE3

Claude Code Setup

Configure ACE MCP with Anthropic's Claude Code CLI agent - Complete step-by-step guide for all platforms.

Automatic Setup (Recommended)

Running automatically creates the MCP config for Claude Code. No manual setup needed. ace login

This creates globally — ACE tools will be available in every project. ~/.claude/.mcp.json

It also installs session hooks automatically — every Claude Code session will start with an agent briefing of what happened since your last session. No extra setup needed.

Already installed? Just run again to auto-create the config. ace login

Claude Code Plugin

Install ACE3 as a Claude Code plugin — bundles 77 MCP tools, 11 skills, and session hooks in one package.

What the plugin includes:

  • 77 MCP tools — memory, issues, decisions, plans, agents, genome, workflows, knowledge graph
  • 11 skills — /ace-search, /log-work, /track-decision, /track-issue, /observe, /plan, /agent-status, /workflow, /context, /debrief, /solutions
  • Session hooks — automatic briefing on session start, work log on session end

Note: You still need ace login for authentication. The plugin handles everything else.

— or set up manually below —

Prerequisites
1

Node.js 18+ installed

Check with: node --version

2

Claude Code CLI installed

3

ACE CLI installed and configured

4

ACE server running

1
Locate Your MCP Config File

Claude Code stores its MCP configuration in a JSON file. The location depends on your operating system:

Config file location:

Open in Terminal: open ~/.claude/

2
Add ACE Configuration

Open the config file in your preferred editor and add the ACE MCP server configuration:

Important: Customize Your Namespace

Replace with a unique namespace for your project. Each project should have its own namespace to keep memories isolated.my-project

If You Have Existing MCP Servers

Add ACE alongside your existing servers. Just add the block inside the object. "ace": {...} mcpServers

3
Start Claude Code

Navigate to your project directory and start Claude Code:

Expected Output

Claude Code will start and automatically detect the ACE MCP server. You should see "ace" listed as an available tool provider.

4
Verify ACE Tools Are Working

Test that ACE is connected by trying these example prompts in Claude Code:

Store a memory:

"Remember that this project uses Next.js 15 with App Router"

Track a decision:

"Track a decision: we're using PostgreSQL for all storage"

Query your knowledge base:

"What issues are currently open?"

Success!

If Claude responds by using ACE tools (you'll see tool calls in the output), your setup is complete!

Troubleshooting

"ace: command not found"

The ACE CLI is not in your PATH. Try these fixes:

  1. Reinstall ACE globally: npm install -g @ace3-memory/ace
  2. Check if npm global bin is in PATH: npm bin -g
  3. Add npm global bin to your PATH in ~/.bashrc or ~/.zshrc
ACE tools not appearing in Claude Code

If ACE tools don't appear:

  1. Verify ACE server is running: ace status
  2. Check your MCP config file for JSON syntax errors
  3. Restart Claude Code completely (quit and reopen)
  4. Verify the config file path is correct for your OS
"Connection refused" or network errors

ACE server may not be running or accessible:

  1. Start ACE server: ace start
  2. Check health: curl http://localhost:7777/health
  3. Check if port 7777 is blocked by firewall
MCP works in one project but not others

This happens when ACE is configured at the project level (via in the project root) instead of at the user level. Project-scoped configs only apply to that single project. .mcp.json

Fix: Add ACE as a user-level MCP server so it works everywhere:

This writes to (user-level) instead of a project-local file. Alternatively, re-run which auto-configures global access. ~/.claude.json ace login

Configuration Scopes

User level (~/.claude.json) — available in all projects.
Project level (.mcp.json) — only that project.
Check your current config with: claude mcp list

Pro Tips

Project-Specific Namespaces

Use different namespaces for different projects (e.g., , ) to keep memories isolated. my-app-frontend, my-app-backend

Session Management

Use and prompts to manage work sessions and keep context organized. /start-session /end-session

View Dashboard

Visit to visualize your memories, issues, and decisions in a knowledge graph. ace3-ai.com/dashboard

Plans

Ask Claude to "generate a project plan" to automatically create issues, decisions, and architecture docs.

Available ACE Tools

Once configured, Claude Code can use all 77 ACE tools:

ace_remember
ace_recall
ace_get_context
ace_search
ace_track_issue
ace_resolve_issue
ace_find_solutions
ace_track_decision
ace_best_practices
ace_get_stats
ace_log_work
ace_architecture
ace_patterns
ace_manage_tags
ace_graph_traverse
ace_graph_connect
ace_graph_related
ace_graph_list
ace_graph_health
ace_graph_analytics
ace_save_plan
ace_list_plans
ace_get_plan
ace_update_plan_task
ace_batch_create
ace_observe
ace_review_observations
ace_trigger_learning
ace_agent_status
ace_trigger_agent
ace_agent_config
ace_agent_history
ace_agent_activity
ace_agent_insights
ace_agent_health
ace_list_namespaces
ace_set_namespace
ace_create_namespace
ace_get_current_namespace