MCP Integration

ActionLayer exposes its full toolkit as an MCP server. Any MCP-compatible agent can read your inbox, submit drafts, approve them, and send — natively, no glue code required.


Endpoint	`https://mcp.actionlayer.dev/mcp`
Transport	Streamable HTTP (MCP spec §3.3)
Auth	`Authorization: Bearer nc_live_…` on every request
Tools / Resources / Prompts	13 / 3 / 2 — see Available tools

SSE-only (legacy) MCP clients are not supported. Make sure your client speaks Streamable HTTP.

4.1 Claude Code

mcp-remote (an npm helper) bridges the local Claude Code MCP runtime to a remote HTTP MCP server. Add this to ~/.claude/settings.json (or your project’s .claude/settings.json):

{
  "mcpServers": {
    "actionlayer": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.actionlayer.dev/mcp"],
      "env": {
        "AUTH_HEADER": "Authorization: Bearer nc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Code and verify with:

“What MCP tools do you have?”

You should see list_threads, get_thread, submit_draft, approve_draft, send_draft, and the rest of the 13 ActionLayer tools. Try a sample prompt:

“Read my latest email and draft a reply asking for more details.”

Claude Code will call list_threads → get_thread → submit_draft and the draft will land in your approval channel for review.

Direct HTTP (no `mcp-remote`)

If you prefer not to depend on mcp-remote, Claude Code also accepts a direct HTTP MCP server:

{
  "mcpServers": {
    "actionlayer": {
      "type": "http",
      "url": "https://mcp.actionlayer.dev/mcp",
      "headers": {
        "Authorization": "Bearer nc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Both forms work. mcp-remote is more convenient when you want to mix in other env-var auth flows.

4.2 OpenClaw

Do not put ActionLayer in OpenClaw’s mcp.servers config. That section is for clients connecting to OpenClaw, not for outbound tools the OpenClaw agent itself uses.Use the AgentSkill bundle below — it’s the tested, production-supported approach.

OpenClaw agents call ActionLayer through an AgentSkill: a markdown file dropped into ~/.openclaw/skills/actionlayer/SKILL.md. The skill teaches the agent how to call the ActionLayer REST API using curl via the exec tool.

Step 1 — Write the SKILL.md

SSH into your OpenClaw server and run a Python heredoc to avoid terminal paste issues:

mkdir -p ~/.openclaw/skills/actionlayer

python3 << 'PYEOF'
import os
content = """---
name: actionlayer
description: Send and receive email, manage drafts, and triage threads via the ActionLayer API.
metadata:
  openclaw:
    emoji: "📧"
---

# ActionLayer — Email Infrastructure

## Auth
Every request: Authorization: Bearer YOUR_API_KEY_HERE
Base URL: https://api.actionlayer.dev/v1
Use exec with curl for all API calls.

## List threads
curl -s -H "Authorization: Bearer YOUR_API_KEY_HERE" "https://api.actionlayer.dev/v1/threads?limit=20"
Optional params: status (open|waiting|draft_pending|closed), needs_review=true, q=search, contact=email

## Get thread
curl -s -H "Authorization: Bearer YOUR_API_KEY_HERE" "https://api.actionlayer.dev/v1/threads/THREAD_ID"
Note the id of the last inbound message before submitting a draft.

## List identities
curl -s -H "Authorization: Bearer YOUR_API_KEY_HERE" "https://api.actionlayer.dev/v1/identities?status=active"
Always call this first to get identity_id.

## Submit draft
curl -s -X POST -H "Authorization: Bearer YOUR_API_KEY_HERE" -H "Content-Type: application/json" \\\\
  -d '{\\"thread_id\\":\\"THREAD_ID\\",\\"identity_id\\":\\"IDENTITY_ID\\",\\"based_on_message_id\\":\\"LAST_MSG_ID\\",\\"body_text\\":\\"Reply.\\",\\"rationale\\":\\"Why.\\"}' \\\\
  "https://api.actionlayer.dev/v1/drafts"
If stale_warning is true in the response, re-read the thread and regenerate.

## Approve draft
curl -s -X POST -H "Authorization: Bearer YOUR_API_KEY_HERE" "https://api.actionlayer.dev/v1/drafts/DRAFT_ID/approve"

## Send draft
curl -s -X POST -H "Authorization: Bearer YOUR_API_KEY_HERE" "https://api.actionlayer.dev/v1/drafts/DRAFT_ID/send"
Returns 202 on success. Returns 409 if stale — reject and regenerate.

## Reject draft
curl -s -X POST -H "Authorization: Bearer YOUR_API_KEY_HERE" -H "Content-Type: application/json" \\\\
  -d '{\\"reason\\":\\"reason\\"}' "https://api.actionlayer.dev/v1/drafts/DRAFT_ID/reject"

## Workflow
1. List threads with needs_review=true
2. Get thread, note last message ID
3. List identities, pick the right one
4. Submit draft with based_on_message_id = last message ID
5. If stale_warning true, regenerate
6. Approve then send
7. If 409 on send, reject and regenerate

## Errors
404 not_found - thread or draft does not exist
409 stale_draft - newer message arrived, regenerate
422 invalid_status - draft cannot be sent in current state
429 rate_limited - slow down and retry
"""
path = os.path.expanduser("~/.openclaw/skills/actionlayer/SKILL.md")
with open(path, "w") as f:
    f.write(content)
print("Wrote:", path)
PYEOF

Step 2 — Inject your API key

Get your key from the dashboard at Settings → API Keys, then:

sed -i 's|YOUR_API_KEY_HERE|nc_live_YOUR_ACTUAL_KEY|g' \
  ~/.openclaw/skills/actionlayer/SKILL.md

Why hardcode and not env-var? OpenClaw’s skills.entries.*.env describes the variable to the agent but doesn’t inject it into exec child processes. ~/.bashrc only loads for interactive login shells — the gateway process doesn’t source it. Hardcoding is the reliable approach.

Step 3 — Restart and verify

openclaw gateway restart

Open a fresh OpenClaw session and ask:

“What skills do you have?”

actionlayer should appear in the list. Then test it:

“List my email threads using ActionLayer.”

OpenClaw troubleshooting

Symptom	Fix
”API key not configured”	Re-run the `sed` command from Step 2
Skill not in list	Confirm the file exists, restart the gateway, start a new session
401 Unauthorized	Key is wrong or revoked — generate a new one and re-run `sed`
409 on send	Draft is stale — reject it, re-read the thread, regenerate

4.3 Codex (OpenAI Agents SDK)

Beta. OpenAI’s MCP support in the Agents SDK is still evolving. The shape below works at the time of writing; check the SDK release notes if it doesn’t behave as expected.

The OpenAI Agents SDK accepts an MCP server as a tool source via MCPServerStreamableHttp (Python) or the equivalent TypeScript class. Pass the ActionLayer URL and your Bearer token:

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

actionlayer = MCPServerStreamableHttp(
    name="actionlayer",
    params={
        "url": "https://mcp.actionlayer.dev/mcp",
        "headers": {
            "Authorization": "Bearer nc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
    },
)

agent = Agent(
    name="EmailAssistant",
    instructions="You handle email replies. Always submit drafts for human approval.",
    mcp_servers=[actionlayer],
)

result = Runner.run_sync(agent, "Read my latest email and draft a polite acknowledgement.")
print(result.final_output)

If your SDK version exposes a different class name (MCPServer, RemoteMCPServer, etc.), pass the same URL + headers — the underlying spec is identical.

Codex CLI / OpenAI Codex IDE

If you’re using Codex via the CLI or an IDE plugin that accepts an ~/.codex/mcp.json (or equivalent), the shape mirrors Claude Code:

{
  "mcpServers": {
    "actionlayer": {
      "type": "http",
      "url": "https://mcp.actionlayer.dev/mcp",
      "headers": {
        "Authorization": "Bearer nc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Codex and confirm by asking it to list available tools.

What your agent gets

Once connected, all platforms expose the same surface:

13 tools — full inbox + draft workflow (list_threads, get_thread, submit_draft, approve_draft, send_draft, reject_draft, edit_draft, list_drafts, get_draft, list_identities, get_identity, list_contacts, get_contact)
3 resources — workspace://current, identities://active, threads://recent
2 prompts — draft_reply, triage_inbox

See Available tools for parameters and return shapes.

Sample prompts

These work the same on Claude Code, OpenClaw, and Codex once the integration is wired:

“Read my latest email and draft a reply.”
“Summarize the threads marked needs_review and tell me which ones look urgent.”
“Find threads from anyone @acme.com and draft a follow-up on the oldest one.”
“Triage my inbox by urgency without sending anything.”

Design constraints (enforced server-side)

These cannot be bypassed by an MCP client:

Auto-send is opt-in — submit_draft never auto-approves unless the identity has auto_approve_replies: true.
Stale drafts are blocked at send time with 409.
TrackOpens and TrackLinks are always false.
Plan limits are enforced before send.
ActionLayer never calls AI providers — your agent is the intelligence.

Getting Started

MCP Server

Examples

4.1 Claude Code

Direct HTTP (no `mcp-remote`)

4.2 OpenClaw

Step 1 — Write the SKILL.md

Step 2 — Inject your API key

Step 3 — Restart and verify

OpenClaw troubleshooting

4.3 Codex (OpenAI Agents SDK)

Codex CLI / OpenAI Codex IDE

What your agent gets

Sample prompts

Design constraints (enforced server-side)

Getting Started

MCP Server

Examples

Documentation Index

​4.1 Claude Code

​Direct HTTP (no mcp-remote)

​4.2 OpenClaw

​Step 1 — Write the SKILL.md

​Step 2 — Inject your API key

​Step 3 — Restart and verify

​OpenClaw troubleshooting

​4.3 Codex (OpenAI Agents SDK)

​Codex CLI / OpenAI Codex IDE

​What your agent gets

​Sample prompts

​Design constraints (enforced server-side)

4.1 Claude Code

Direct HTTP (no `mcp-remote`)

4.2 OpenClaw

Step 1 — Write the SKILL.md

Step 2 — Inject your API key

Step 3 — Restart and verify

OpenClaw troubleshooting

4.3 Codex (OpenAI Agents SDK)

Codex CLI / OpenAI Codex IDE

What your agent gets

Sample prompts

Design constraints (enforced server-side)