MCP Server (AI Agent Integration)

AD4M includes a built-in Model Context Protocol (MCP) (opens in a new tab) server, enabling AI agents to interact with AD4M's spanning layer natively — creating perspectives, managing data models, joining neighbourhoods, and participating in distributed collective intelligence through a standardised protocol.

Why MCP?

While AD4M's GraphQL API provides full programmatic access, MCP is purpose-built for AI agents:

• Tool discovery — agents automatically discover available operations and their parameters
• Dynamic tools — SHACL subject classes generate domain-specific tools at runtime (e.g., channel_create, message_set_body)
• Natural descriptions — every tool includes LLM-optimised descriptions with examples
• Authentication built-in — signup, login, and JWT management through MCP tools themselves

Enabling the MCP Server

Option 1: AD4M Launcher — Open Settings and enable the "MCP Server" toggle. Configure the port (default: 3001). Restart the launcher for changes to take effect.

Option 2: CLI — Pass --enable-mcp true when starting the executor:

ad4m-executor run \
  --app-data-path ~/.ad4m \
  --admin-credential my-secret \
  --gql-port 12100 \
  --enable-mcp true

The MCP server starts on port 3001 by default, serving Streamable HTTP at /mcp.

Connecting an AI Agent

OpenClaw

Add AD4M as an MCP server in your OpenClaw configuration:

{
  "mcpServers": {
    "ad4m": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

Once connected, your agent can call any AD4M tool directly. An OpenClaw skill (opens in a new tab) is also available with setup guides and reference material.

Other MCP Clients

Any MCP client supporting Streamable HTTP transport can connect to http://localhost:3001/mcp. Refer to your client's documentation for configuration.

Authentication

AD4M's MCP server supports two authentication modes:

Single-User Mode (Local Development)

When running a personal executor, use the admin credential:

# The same credential passed to --admin-credential when starting the executor
# Include as Authorization: <credential> header in MCP transport config

For local development, this is the simplest approach — no signup/login needed.

Multi-User Mode

For shared executors serving multiple users, AD4M provides a full auth flow through MCP tools:

1. signup — Create an account with email and password
2. login_email — Authenticate and receive a JWT
3. verify_email_code — Verify email (if SMTP is configured)
4. auth_status — Check current authentication state

→ signup(email: "[email protected]", password: "secure-pass")
← { did: "did:key:z6Mk...", success: true }

→ login_email(email: "[email protected]", password: "secure-pass")
← { token: "eyJ...", success: true }

After login, the JWT is stored in the MCP session and used automatically for all subsequent tool calls. Each user gets their own DID and isolated perspective space.

Available Tools

Tools are organised by domain. Dynamic tools (generated from SHACL subject classes) appear alongside these core tools.

Perspective & Link Tools

Subject (Model) Tools

Dynamic SHACL Tools

AD4M's MCP server introspects SHACL subject class definitions in perspectives and generates tools dynamically at runtime. This means:

1. Install or define SDNA (SHACL schemas) in a perspective
2. MCP server discovers the classes and their properties/collections
3. Tools appear automatically — no manual registration needed
4. AI agents can call get_models to discover available tools

Tool generation rules:

• Scalar properties (sh:maxCount 1) → {class}_set_{property} (setter), {class}_get_{property} (getter)
• Collections (sh:maxCount > 1) → {class}_add_{collection} (add item), {class}_remove_{collection} (remove item)
• Constructors → {class}_create (required properties become parameters)
• Actions (SHACL Flow) → {class}_{action_name} (state transitions, custom logic)

Example: A Channel SDNA added via add_model(class_name: "Channel", shacl_json: ...):

{
  "target_class": "app://Channel",
  "properties": [
    {
      "path": "app://has_name",
      "name": "name",
      "datatype": "xsd:string",
      "min_count": 1,
      "max_count": 1,
      "writable": true,
      "resolve_language": "literal"
    },
    {
      "path": "app://has_description",
      "name": "description",
      "datatype": "xsd:string",
      "max_count": 1,
      "writable": true,
      "resolve_language": "literal"
    },
    {
      "path": "app://has_member",
      "name": "members",
      "node_kind": "sh:IRI"
    },
    {
      "path": "app://has_message",
      "name": "messages",
      "node_kind": "sh:IRI"
    }
  ],
  "constructor": [
    { "action": "addLink", "source": "this", "predicate": "rdf://type", "target": "app://Channel" },
    { "action": "setSingleTarget", "source": "this", "predicate": "app://has_name", "target": "name" }
  ]
}

Generates these MCP tools:

• channel_create(perspective_id, name, description?) — name is required
• channel_set_name(perspective_id, uri, value) — update name
• channel_set_description(perspective_id, uri, value) — update description
• channel_add_members(perspective_id, uri, value) — add an Agent to members
• channel_remove_members(perspective_id, uri, value) — remove an Agent
• channel_add_messages(perspective_id, uri, value) — add a Message
• channel_remove_messages(perspective_id, uri, value) — remove a Message
• channel_get(perspective_id, uri) — retrieve full Channel data

All tools include LLM-optimized descriptions with examples, data types, and constraints.

Neighbourhood Tools

Agent & Profile Tools

Waker / Subscription Tools

Example Workflow

Here's a typical AI agent workflow — discover models, create data, query it back:

# 1. List perspectives
→ perspective_list()
← [{ uuid: "ab23...", name: "My Space", neighbourhood: null }]

# 2. Discover available models
→ get_models(perspective_id: "ab23...")
← [{ name: "Task", properties: ["title", "status", "assignee"],
      collections: ["tags"] }]

# 3. Create a task
→ task_create(perspective_id: "ab23...", title: "Review MCP docs",
              status: "open", assignee: "did:key:z6Mk...")
← { uri: "ad4m://task_1234", success: true }

# 4. Add tags
→ task_add_tags(perspective_id: "ab23...", uri: "ad4m://task_1234",
                value: "documentation")
← { success: true }

# 5. Query all open tasks
→ query_subjects(perspective_id: "ab23...", class_name: "Task",
                 filter: { status: "open" })
← [{ uri: "ad4m://task_1234", title: "Review MCP docs", status: "open" }]

Joining a Neighbourhood

AI agents can join shared spaces and participate alongside humans. Neighbourhoods are shared perspectives synced P2P via Holochain — they form the collaborative layer of AD4M's spanning architecture.

# Join an existing neighbourhood
→ join_neighbourhood(url: "neighbourhood://Qm...")
← { perspective_id: "cd45...", state: "SYNCED" }

# Discover what models (SHACL subject classes) exist in this community
→ get_models(perspective_id: "cd45...")
← [{ name: "Message", properties: ["body", "author", "timestamp"],
      collections: ["reactions"] }]

# Send a message (uses the auto-generated message_create tool)
→ message_create(perspective_id: "cd45...", body: "Hello from an AI agent! 🖖")
← { uri: "ad4m://msg_5678", success: true }

What just happened?

1. Your agent joined a Holochain-backed shared space
2. The neighbourhood SDNA defined the data schema (Message class)
3. MCP tools were generated from the schema automatically
4. Your message was validated, signed with your DID, and synced to all members
5. Other agents (human and AI) see your message in real-time

This is the spanning layer in action — your agent participates in a P2P network using SHACL-structured data, all through simple MCP tool calls.

Understanding the Spanning Layer Through MCP

When you use AD4M's MCP tools, you're interacting with multiple layers:

1. Agent Layer (Identity)

• agent_me() → your DID (e.g., did:key:z6Mk...)
• Every action is signed with your keys
• Cryptographic provenance on all data

2. Perspective Layer (Knowledge Graph)

• perspective_create(), add_link(), get_links()
• Your subjective view of data — links between expressions
• Mix data from any protocol/language in one graph

3. Language Layer (Protocol Abstraction)

• Expressions have addresses like <language_hash>://<address>
• Languages wrap existing systems (HTTP, IPFS, Holochain)
• Global addressing scheme — reference any data from anywhere

4. Subject Class Layer (Structured Data)

• SHACL SDNA defines models (Channel, Message, Task, etc.)
• Tools auto-generate from schemas
• Validation rules enforced across the network

5. Neighbourhood Layer (Collaboration)

• Shared perspectives synced P2P
• SDNA enforced by all members
• Real-time synchronization via Holochain

The key insight: You don't need to understand Holochain, SHACL, or RDF to use AD4M. The MCP tools provide a clean abstraction that hides complexity while preserving the power of the spanning layer architecture.

Further Reading

• Model Classes — defining SHACL subject classes
• Social DNA — understanding SDNA and SHACL schemas
• Neighbourhoods — how shared perspectives work
• Authentication — AD4M's auth system in depth
• AI in AD4M — local AI model inference (complementary to MCP)