ACE MCP Client Setup¶

The ACE MCP server runs over stdio, so any MCP client that can launch a local command can connect to it.

This guide focuses on wiring ace-mcp into popular clients. For the full tool reference, environment variables, and safety controls, see the MCP Server guide.

Prerequisites¶

Install ACE with the MCP extra:

pip install "ace-framework[mcp]"
# or
uv add "ace-framework[mcp]"

Set the model and provider credentials you want the server to use:

export ACE_MCP_DEFAULT_MODEL="gpt-4o-mini"
export OPENAI_API_KEY="sk-..."

Verify the server starts:

ace-mcp

It should log startup information to stderr and then wait for stdio input.

Claude Code¶

Anthropic recommends managing Claude Code MCP servers with the claude mcp commands. A user-scoped server can be added with:

claude mcp add-json -s user ace '{
  "type": "stdio",
  "command": "ace-mcp",
  "env": {
    "ACE_MCP_DEFAULT_MODEL": "gpt-4o-mini",
    "OPENAI_API_KEY": "sk-..."
  }
}'

Useful variants:

-s project stores the server in .mcp.json for the current repo.
claude mcp list shows configured servers.
claude mcp get ace prints the saved config.

Once added, you can ask Claude Code to use ACE directly:

Use ace.ask with session_id "repo-default" to summarize the conventions in this repo.

Cursor¶

Cursor supports local stdio MCP servers. Add a server from the MCP settings UI or your MCP config using this shape:

{
  "mcpServers": {
    "ace": {
      "command": "ace-mcp",
      "env": {
        "ACE_MCP_DEFAULT_MODEL": "gpt-4o-mini",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

After saving, refresh MCP servers in Cursor and confirm the ACE tools appear.

Windsurf¶

Windsurf exposes MCP configuration through Windsurf Settings > Cascade > MCP Servers. Add a stdio server using the same command/env shape:

{
  "mcpServers": {
    "ace": {
      "command": "ace-mcp",
      "env": {
        "ACE_MCP_DEFAULT_MODEL": "gpt-4o-mini",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Restart the MCP connection if the tools do not appear immediately.

Smoke Test with MCP Inspector¶

Before debugging a client-specific setup, verify the server generically with the MCP Inspector:

npx @modelcontextprotocol/inspector ace-mcp

If the server starts and the six ACE tools appear, the remaining work is client configuration rather than ACE itself.

Troubleshooting¶

`ace-mcp` is not found¶

Confirm the package was installed with the mcp extra.
Run which ace-mcp (or the equivalent on your platform) and use the full path in the client config if needed.

The client connects but no tools appear¶

Start ace-mcp manually first to confirm it launches cleanly.
Check stderr logs from the server.
Set ACE_MCP_LOG_LEVEL=DEBUG for more verbose logging.

Save/load should stay inside a safe directory¶

Set ACE_MCP_SKILLBOOK_ROOT to constrain ace.skillbook.save and ace.skillbook.load to a specific directory.