MCP Interface¶

AAM exposes its full functionality as an MCP (Model Context Protocol) server, allowing AI agents and IDE integrations to manage packages, sources, and configuration programmatically. Any MCP-compatible client --- Cursor, VS Code, Claude Desktop, Windsurf, or custom toolchains --- can connect to AAM and operate it directly.

What Is the MCP Interface?¶

The Model Context Protocol (MCP) is an open standard that lets AI agents call tools and read resources from external services over a structured transport (stdio or HTTP/SSE). AAM implements an MCP server using FastMCP, exposing CLI functionality as tools (callable actions) and resources (passive data endpoints).

flowchart LR
    IDE["IDE / AI Agent<br/>(Cursor, Claude Desktop, etc.)"] -->|MCP protocol| AAM["AAM MCP Server<br/>(aam mcp serve)"]
    AAM -->|reads/writes| Config["~/.aam/config.yaml"]
    AAM -->|manages| Packages["~/.aam/packages/"]
    AAM -->|clones/fetches| Sources["~/.aam/cache/git/"]

    style IDE fill:#e3f2fd
    style AAM fill:#f3e5f5
    style Config fill:#e8f5e9
    style Packages fill:#e8f5e9
    style Sources fill:#e8f5e9

Instead of typing aam install @author/my-skill in a terminal, your AI agent calls the aam_install tool through MCP and gets structured results back.

Starting the MCP Server¶

Basic (Read-Only)¶

aam mcp serve

By default the server starts in read-only mode on stdio transport. This is the safest option --- agents can search, list, and inspect packages but cannot modify anything.

With Write Access¶

aam mcp serve --allow-write

Enables mutating tools (install, uninstall, publish, etc.). Use this when you trust the connected agent to make changes.

Full Options¶

Example: HTTP Transport¶

aam mcp serve --transport http --port 9000 --allow-write

This starts an SSE server on port 9000 with full read/write access, suitable for remote or multi-client setups.

IDE Integration¶

Cursor¶

Add AAM as an MCP server in your Cursor settings (.cursor/mcp.json):

{
  "mcpServers": {
    "aam": {
      "command": "aam",
      "args": ["mcp", "serve", "--allow-write"]
    }
  }
}

Once configured, Cursor's AI agent can call AAM tools directly --- searching for packages, installing skills, managing sources --- all without leaving the editor.

Claude Desktop¶

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "aam": {
      "command": "aam",
      "args": ["mcp", "serve", "--allow-write"]
    }
  }
}

VS Code / Other MCP Clients¶

Any client that supports the MCP stdio transport can connect by spawning aam mcp serve as a subprocess.

Available Tools¶

AAM exposes 29 tools split into two categories with a safety-first design: read tools are always available, write tools require explicit opt-in.

Read Tools (17 tools, always available)¶

These tools are safe to call at any time --- they never modify state.

Package Discovery¶

Package Integrity¶

Source Management¶

Configuration & Diagnostics¶

Write Tools (12 tools, require --allow-write)¶

These tools modify state and are excluded by default for safety.

Package Management¶

Package Authoring¶

Source Management¶

Configuration¶

Available Resources¶

Resources provide passive, read-only data that agents can fetch at any time without side effects.

Safety Model¶

AAM's MCP server follows a read-only-by-default principle:

This design ensures that agents cannot accidentally install, remove, or publish packages unless explicitly authorized.

Example Agent Workflows¶

Discover and Install a Skill¶

An AI agent connected via MCP might follow this workflow:

1. Search for relevant skills: call aam_search with a query
2. Inspect a candidate: call aam_info for metadata and dependencies
3. Install the skill: call aam_install with the package name
4. Verify the installation: call aam_verify to check file integrity

Audit Installed Packages¶

1. List installed packages: call aam_list
2. Check for outdated versions: call aam_outdated
3. Upgrade stale packages: call aam_upgrade
4. Run diagnostics: call aam_doctor to confirm health

Explore Available Sources¶

1. List configured sources: call aam_source_list
2. Scan a source: call aam_source_scan to discover artifacts
3. Find candidates: call aam_source_candidates for unpackaged artifacts
4. Add a new source: call aam_source_add with the git URL

Related Documentation¶

• Getting Started --- Install AAM and configure your environment
• CLI Reference --- The same commands exposed as MCP tools
• Platform Guides --- Deploy artifacts to Cursor, Claude, Copilot, and Codex
• Configuration --- Configure AAM behavior