Adapter Reference

An adapter encapsulates the format of a specific AI environment.

Summary

AI environment	Target ID	Default base dir	Skills	MCP config
Claude Code	claude-code	~/.claude	skills/<name>/SKILL.md	~/.claude.json
Cursor	cursor	~/.cursor	skills/<name>/SKILL.md	mcp.json
Codex CLI	codex	~/.codex	skills/<name>/SKILL.md	config.toml

Claude Code

MCP servers are written to ~/.claude.json, in the mcpServers JSON section — this is the file Claude Code reads for MCP server definitions (not settings.json, which stores policies like allowedMcpServers):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "API_KEY": "..."
      }
    }
  }
}

Cursor

Cursor uses the mcpServers JSON format in mcp.json.

The entry structure is the same as for Claude Code.

Cursor may create ~/.cursor/mcp.json as an empty file before any server is configured. AIM treats an empty config file as an empty object {} — MCP server installation continues correctly.

Codex CLI

Codex CLI uses TOML:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
API_KEY = "..."

Reading an environment on import

An adapter can also read an environment, not just write to it: this is what aiman import skill and aiman import mcp rely on.

AI environment	Where skills are read from	Where the MCP config is read from
Claude Code	~/.claude/skills/<name>/SKILL.md and flat ~/.claude/skills/*.md (the flat file wins)	~/.claude.json, then ~/.claude/settings.json for names not found there
Cursor	~/.cursor/skills/<name>/SKILL.md	~/.cursor/mcp.json
Codex CLI	~/.codex/skills/<name>/SKILL.md	~/.codex/config.toml

Only stdio servers — those that define a command — can be imported. The adapter does not pass entries declared with "type": "http", "type": "sse", or a bare "url" to the inventory: for such a server, aiman import mcp <name> fails and names the reason (CLI Reference).

Removing items from an environment

An adapter can not only install items but also remove them. Removal happens only through aiman apply --loadout <name>, and only for items known to the inventory (CLI Reference).

What is removed	How
Skill	the <base dir>/skills/<name>/ directory is removed in full, including reference files
MCP server	only that server's entry is removed from the environment config; other entries and the file itself are preserved

For Claude Code, the entry is removed from ~/.claude.json — the same file it was installed into. If the entry or the file is missing, removal completes without an error.

Overriding paths

If an environment is installed in a non-standard location, set the base dir in aim.local.yaml:

environments:
  claude-code: /custom/path/.claude

The adapter itself knows where skills and the MCP config are located within the base dir.