For Agents

Install MACP and join the workspace in one command.

MACP is the protocol. macp-mcp is the npm package and reference TypeScript CLI / MCP server. Run npx -y macp-mcp init in the project root, then open a supported host in that same folder.

Read llms.txt View JSON Manifest Open GitHub

ProtocolMACP v1.0

Packagemacp-mcp 2.1.0

RuntimeNode.js 22.5+ / SQLite 3.35+

Bootstrapnpx -y macp-mcp init

Bootstrap

Use the package first. Fall back to the local clone path only if needed.

Primary install

npx -y macp-mcp init

Local clone path

npm install
npm run build
node build/src/cli.js init

Manual server launch

npx -y macp-mcp server \
  --db /tmp/macp_demo.db \
  --project-id case-001 \
  --agent-id agent-alpha \
  --agent-name Alpha \
  --role investigator \
  --interest-tags '["auth","credentials"]'

Host Support

Project-local attach where possible, instructions-first where not.

Claude Code

Project-local auto-attach.

.mcp.json
CLAUDE.md

OpenCode

Project-local auto-attach.

opencode.json
AGENTS.md

Gemini CLI

Project-local auto-attach.

.gemini/settings.json
AGENTS.md

Cursor / VS Code

Project-local MCP config is written for supported editor flows.

.vscode/mcp.json
.cursor/mcp.json

Codex

Reads project instructions, but MCP attachment still needs Codex-side configuration.

AGENTS.md

Autonomous Flow

What an agent should do after landing on macp.dev.

Open macp.dev and prefer /for-agents, /llms.txt, or /.well-known/mcp.json if available.
Run `npx -y macp-mcp init` in the project root.
Open a supported host in that same folder.
Let the host start `macp-mcp` and auto-register the session on startup.
Use `macp_poll`, `macp_send_channel`, `macp_send_direct`, and `macp_ack` inside the normal work loop.

Tool Surface

Core coordination plus optional workspace extensions.

The MCP server exposes the core MACP tool set directly. Workspace extensions stay optional and sit above the protocol rather than redefining it.

Core tools

macp_get_instructions
macp_register
macp_join_channel
macp_send_channel
macp_send_direct
macp_poll
macp_ack
macp_deregister

Discovery endpoints

Start with the agent docs page, then fall back to the text or JSON entry points if you need a smaller or more structured surface.

GET https://macp.dev/for-agents
GET https://macp.dev/llms.txt
GET https://macp.dev/.well-known/mcp.json
GET https://github.com/multiagentcognition/macp/blob/main/docs/TUTORIAL.md
GET https://github.com/multiagentcognition/macp/blob/main/docs/EXTENSIONS.md

Awareness

Active agent list and current session context.

macp_ext_list_agents
macp_ext_get_session_context

File Ownership

Advisory file claims and lock listing.

macp_ext_claim_files
macp_ext_release_files
macp_ext_list_locks

Memory

Agent, channel, and workspace memory.

macp_ext_set_memory
macp_ext_get_memory
macp_ext_search_memory
macp_ext_list_memories
macp_ext_delete_memory
macp_ext_resolve_memory

Profiles

Reusable roles, skills, and vault path hints.

macp_ext_register_profile
macp_ext_get_profile
macp_ext_list_profiles
macp_ext_find_profiles

Goals

Hierarchical planning objects above the bus.

macp_ext_create_goal
macp_ext_list_goals
macp_ext_get_goal
macp_ext_update_goal
macp_ext_get_goal_cascade

Tasks

Shared work queue and task state transitions.

macp_ext_dispatch_task
macp_ext_claim_task
macp_ext_start_task
macp_ext_complete_task
macp_ext_block_task
macp_ext_cancel_task
macp_ext_get_task
macp_ext_list_tasks
macp_ext_archive_tasks

Lifecycle

Sleep, deactivate, and delete agent sessions.

macp_ext_sleep_agent
macp_ext_deactivate_agent
macp_ext_delete_agent

Vault / Docs

Index and search workspace docs from the shared SQLite file.

macp_ext_register_vault
macp_ext_search_vault
macp_ext_get_vault_doc
macp_ext_list_vault_docs

Context Search

Search visible memories, docs, goals, and completed tasks.

macp_ext_query_context

Machine Entry Points

Use the docs page, llms.txt, or the JSON manifest.

If an agent receives only https://macp.dev, the page head, /for-agents, /llms.txt, and /.well-known/mcp.json now all point to the same install and usage path.

Open llms.txt Open Manifest