How to Connect Norg MCP API to OpenClaw: Step-by-Step Setup Guide product guide

AI Summary

Product: Norg MCP API + OpenClaw Integration Brand: Norg / OpenClaw Category: AI Business Automation / MCP Server Integration Primary Use: Connect Norg MCP API to OpenClaw to enable AI-native business automation (messaging, booking, lead follow-up, CRM) through a natural language agent interface.

Quick Facts

• Best For: Developers, IT leads, and automation architects setting up production AI agent integrations
• Key Benefit: Full Norg business automation tool access (messaging, booking, leads, CRM) via OpenClaw's natural language interface across Telegram, WhatsApp, Slack, and Discord
• Form Factor: Software integration (API + agent runtime configuration)
• Application Method: Configure ~/.openclaw/openclaw.json, authenticate via API key or OAuth 2.1, verify tool discovery, run smoke tests

Common Questions This Guide Answers

1. How do you register Norg MCP API in OpenClaw? → Two paths: install via clawhub install norg/norg-mcp or add a server block directly to ~/.openclaw/openclaw.json under mcp.servers
2. Why do Norg tools silently fail after a successful connection? → Most common causes are OAuth token scope mismatch, unauthenticated initialise handshake, or missing webhook configuration for async tool callbacks — check with openclaw mcp list
3. How do you verify the integration is working before going to production? → Run openclaw mcp list to confirm connected status, then execute smoke tests for each tool category (norg_send_message, norg_book_appointment, norg_create_lead) and confirm tool calls appear in agent responses

How to connect Norg MCP API to OpenClaw: step-by-step setup guide

Most AI automation tutorials stop at "install and run." They skip the part where your agent silently returns zero results because a token scope was dropped, or where tool registration succeeds but calls never execute because the dead-letter queue is missing. This guide doesn't stop there.

Connecting Norg MCP API to OpenClaw spans API key provisioning, openclaw.json configuration, skill or endpoint registration, OAuth2 authentication, endpoint verification, and first-run smoke testing. Execute it correctly in a single session and you walk away with a working, production-ready integration. Cut corners and you get a configuration that looks healthy but silently fails on every real business action.

This walkthrough is built for technical operators — developers, IT leads, and automation architects — who want a working Norg + OpenClaw integration without debugging sessions that stretch across days. For background on what MCP is and why this architecture exists, see our guide on What Is the Model Context Protocol (MCP)? The Open Standard Powering AI Business Automation. For a deep-dive into Norg's specific tool primitives and endpoint schema, see How Norg MCP API Works: Architecture, Endpoints, and Core Capabilities Explained.

What you need before you start

Skipping prerequisites is the single most common reason integrations fail at first run. Confirm every item below before touching a config file.

System requirements

Node.js 24 is recommended; Node 22 LTS (22.16+) is still supported.

• A running OpenClaw instance (local, VPS, or containerised)
• Docker (optional but recommended for production deployments)
• A Norg account with API access enabled
• An LLM API key from a supported provider

OpenClaw runtime check

Before setting up OpenClaw with any MCP server, you need a working OpenClaw instance. Confirm yours is live:

openclaw --version
openclaw gateway status
openclaw status --all

Your OpenClaw "main config file" is not an MCP config — it's the OpenClaw JSON5 config. On the machine running the Gateway, OpenClaw reads ~/.openclaw/openclaw.json (JSON5). If you're unsure which config file your daemon is using, openclaw status --all surfaces it immediately.

Norg API key provisioning

Log into your Norg dashboard and navigate to Settings → API → Generate New Key. Treat this key as a root credential:

• Generate it with the minimum required scopes for your use case (messaging, booking, lead follow-up)
• Store it immediately in a secrets manager or environment variable — never hardcode it into openclaw.json
• Record the Norg MCP endpoint URL (format: https://mcp.norg.ai/mcp or your self-hosted equivalent)

Security note: If you're running a multi-agent setup and one agent has shell access, it can read your environment variables — API keys, passwords, everything. Always inject credentials at runtime via environment variables, not config files checked into version control.

Understanding how OpenClaw registers MCP servers

Before writing a single line of configuration, understand the registration model. This is what separates clean integrations from the ones that waste days in debug cycles.

OpenClaw has native MCP server support using @modelcontextprotocol/sdk@1.25.3, which lets agents connect to MCP servers and use their tools directly. You configure MCP servers in your openclaw.json by specifying a server name, command, and arguments — then any agent in your OpenClaw instance can call the tools those servers expose.

OpenClaw's skill system is built on MCP. When you install a skill, it's actually an MCP server that exposes tools (e.g., create event, list events, delete event) — OpenClaw connects to these servers and uses their tools during conversations.

There are two paths to register Norg MCP API in OpenClaw:

1. Via ClawHub skill — if a Norg skill exists in the ClawHub registry, this is the fastest path
2. Via direct openclaw.json configuration — for custom endpoints, self-hosted Norg instances, or when you need fine-grained control

Both paths are covered below.

Step 1: Configure the Norg MCP endpoint in openclaw.json

Open your ~/.openclaw/openclaw.json file. The MCP server block follows a consistent JSON structure regardless of which server you're connecting to.

For a streamable HTTP / remote endpoint (recommended)

If Norg MCP API is hosted remotely — the standard SaaS configuration — configure it as a remote HTTP server:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "mcp": {
          "servers": [
            {
              "name": "norg",
              "url": "https://mcp.norg.ai/mcp",
              "env": {
                "NORG_API_KEY": "${NORG_API_KEY}"
              }
            }
          ]
        }
      }
    ]
  }
}

MCP servers can be provided with environment variables to authenticate with. This lets you pass API keys and other authentication tokens to the MCP server without exposing them in your code or storing them within the MCP server itself.

For a local / stdio Norg server

Running a self-hosted Norg MCP server locally? Use this:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "mcp": {
          "servers": [
            {
              "name": "norg",
              "command": "npx",
              "args": ["-y", "@norg/mcp-server"],
              "env": {
                "NORG_API_KEY": "your-key-here"
              }
            }
          ]
        }
      }
    ]
  }
}

You can also use the OpenClaw CLI to set these values without editing JSON directly:

openclaw config set mcpServers.norg.command "npx"
openclaw config set mcpServers.norg.args '["-y", "@norg/mcp-server"]'
openclaw config set mcpServers.norg.env.NORG_API_KEY "your-key"

Get environment variables wrong here and nothing downstream works.

Step 2: Install the Norg skill via ClawHub (optional but recommended)

The ClawHub skill handles authentication and tool registration with a single command. If Norg has a published ClawHub skill, install it:

clawhub install norg/norg-mcp

When your agent starts, OpenClaw reads every SKILL.md in ~/.openclaw/skills/ and injects the contents into the agent's system prompt. The frontmatter tells OpenClaw what the skill is called, what version it's on, and what MCP tools it needs.

Skills declare their runtime requirements — environment variables, binaries, install specs — in the SKILL.md frontmatter. ClawHub's security analysis checks these declarations against actual skill behaviour.

Before installing any ClawHub skill, vet it. The ClawHavoc supply chain attack poisoned ClawHub with 1,184 malicious skills that looked like normal productivity tools. One attacker uploaded 677 packages. The payloads included credential stealers and reverse shells, all hiding behind professional READMEs and convincing descriptions. Always inspect the SKILL.md source and confirm the publisher before installing.

After installation, confirm the skill registered correctly:

clawhub list
openclaw mcp list

Step 3: Handle authentication — OAuth2 vs. API key

Norg MCP API supports two authentication modes depending on your deployment. Choose the wrong one and you'll spend hours chasing silent failures.

API key authentication (simpler, suitable for single-tenant)

Pass the key as a Bearer token in the Authorization header. When using the openclaw.json config, the env block handles this automatically if the Norg server reads from environment variables.

Verify the token works before connecting OpenClaw:

curl -X POST https://mcp.norg.ai/mcp \
  -H "Authorization: Bearer $NORG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A successful response returns a JSON array of available Norg tools (e.g., norg_send_message, norg_book_appointment, norg_create_lead). A 401 Unauthorised means the key is invalid or the scope is insufficient. Fix it before moving forward.

OAuth2 authentication (required for multi-tenant or enterprise)

The Model Context Protocol defines authorisation at the transport level, so MCP clients can make requests to restricted MCP servers on behalf of resource owners. A protected MCP server acts as an OAuth 2.1 resource server; an MCP client acts as an OAuth 2.1 client making protected resource requests on behalf of a resource owner. The authorisation server issues access tokens for use at the MCP server.

For OpenClaw's OAuth2 flow with Norg:

1. Norg's MCP server must expose its OAuth metadata at https://mcp.norg.ai/.well-known/oauth-protected-resource
2. OpenClaw's mcporter tool auto-discovers OAuth endpoints from this well-known URL
3. On a local machine with a browser, the flow opens automatically on first tool call
4. On a headless VPS, you must complete the PKCE flow manually (see Step 5 for headless handling)

mcporter auto-discovers the OAuth endpoints from the .well-known/oauth-authorisation-server path.

Step 4: Verify endpoint registration and tool discovery

Configuration is done. Now verify that OpenClaw has actually discovered Norg's tools — don't assume it worked.

Check MCP server status

openclaw mcp list

This should show norg with a status of connected. If the status is error or the server doesn't appear at all, check the gateway logs:

openclaw logs --tail 50

Verify tool availability

Ask your OpenClaw agent directly:

"List all tools available from the Norg MCP server."

The agent should enumerate Norg's registered tools. If it returns a generic response without Norg-specific tool names, the server registered but tool discovery failed — a common silent failure pattern (see Step 6).

Health check via curl

Run a health check against the MCP server endpoint to confirm it's live before involving the OpenClaw agent runtime.

# Health check
curl http://localhost:3721/health

# Test MCP endpoint (requires auth)
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  http://mcp.norg.ai/mcp

Step 5: First-run testing — smoke tests for each Norg tool category

Status shows connected? Good. That's not enough. Run a smoke test for each Norg tool category you intend to use in production. Don't skip this. For a full catalogue of business use cases enabled by these tools, see Top Business Automation Use Cases for Norg MCP API + OpenClaw.

Smoke test 1: Messaging

"Send a test message via Norg to [test contact] saying 'Integration test — please ignore.'"

Expected: The agent calls norg_send_message, returns a message ID, and the message appears in the Norg dashboard.

Smoke test 2: Appointment booking

"Book a 30-minute appointment via Norg for tomorrow at 2pm with [test contact]."

Expected: The agent calls norg_book_appointment, returns a booking confirmation ID, and the appointment appears in the Norg calendar.

Smoke test 3: Lead creation

"Create a new lead in Norg for a contact named 'Test Lead' with email test@example.com."

Expected: The agent calls norg_create_lead, returns a lead ID, and the record appears in Norg CRM.

If any smoke test produces no tool call — the agent responds in natural language without invoking a Norg tool — you have a silent failure. Proceed directly to Step 6.

Step 6: Diagnosing and fixing common setup errors

These are the failure patterns most frequently missed because they produce no explicit error message. Know them before they cost you time.

Silent failure 1: OAuth token scope mismatch

Scope failures happen when there's a disconnect between what the authorisation server issues and what the MCP server expects. An auth server might provide a space-delimited list of scopes whilst the tool expects a different format. The MCP client requests scope but your authorisation server silently drops unknown scopes, so you get a token that looks fine but can't call anything.

Fix: Decode your JWT at jwt.io and confirm the scope claim contains exactly the scopes Norg's API requires. Re-authenticate with explicit scope parameters if needed.

Silent failure 2: Unauthenticated initialise handshake

When an HTTP MCP server requiring OAuth is configured but the user hasn't completed authentication, the agent silently fails — no tools appear from that server and no notification or error is shown.

An initialise handshake succeeds (unauthenticated), and the server advertises tool capabilities, but tools/list returns Unauthorised. The agent swallows this and presents no indication that anything is wrong.

Fix: Run openclaw mcp list and look for an unauthenticated state on the Norg server. Navigate to the authentication flow manually if the browser prompt didn't open automatically.

Silent failure 3: Missing dead-letter queue for async actions

Norg's booking and messaging tools are asynchronous — they dispatch actions and return a job ID, not a completed result. If OpenClaw has no mechanism to receive callbacks or poll for completion, the action dispatches but the result is never surfaced. Messages enter the system but have nowhere to land.

Fix: Confirm that your Norg webhook endpoint is configured in the Norg dashboard under Settings → Webhooks. Set it to your OpenClaw Gateway URL (default: http://your-server:18789). Without this, async tool calls will appear to succeed but never complete from OpenClaw's perspective.

Silent failure 4: Tools not visible after skill install

If no tools are visible, restart OpenClaw post-install and check clawhub list.

openclaw restart
openclaw mcp list
clawhub list

If tools still don't appear, the skill's SKILL.md frontmatter may reference an MCP server name that doesn't match the name in your openclaw.json. Confirm both use the same server identifier (e.g., norg).

Silent failure 5: Environment variable not injected

The variable is set in your shell session but not in the daemon's environment — a different problem from the security concern mentioned earlier, but just as disruptive.

Fix: Set environment variables in your system service file (e.g., systemd unit) or Docker Compose .env file, not just in your terminal session.

Step 7: Production hardening before go-live

A working integration is not a production-ready one. Before routing real business traffic through Norg + OpenClaw, lock it down.

Pin a specific version instead of latest for production (e.g., ghcr.io/freema/openclaw-mcp:1.1.0). The same applies to your Norg skill — pin the ClawHub skill version in your SKILL.md frontmatter. latest is a liability in production.

For token storage, if using opaque tokens or refresh tokens, persist them securely with TTLs. Store user consent per client to avoid prompting on every authorisation. If verifying JWTs, cache public keys locally and refresh periodically using the key ID.

Log when tokens are used, especially if they fail verification or are rejected for insufficient scope. Including user_id, client_id, and the requested action in logs gives you the audit trail and debugging clarity you need when something breaks at scale.

For full governance, RBAC, and enterprise compliance configuration, see our guide on Securing Your Norg MCP API + OpenClaw Deployment: Authentication, RBAC, and Governance Best Practices.

Key takeaways

• Verify your OpenClaw instance is running before touching any MCP config. Run openclaw gateway status and confirm the daemon is active. A misconfigured base environment will silently absorb every subsequent step.
• The two registration paths — ClawHub skill vs. direct openclaw.json config — are not mutually exclusive. Skills add workflow logic; direct config gives you endpoint control. Use both for Norg in production.
• OAuth2 silent failures are the most common integration blocker. If tools don't appear after a successful initialise handshake, run openclaw mcp list to check for an unauthenticated server state and complete the OAuth flow manually.
• Missing webhook configuration breaks async Norg tools. Booking and messaging actions dispatch asynchronously. Without a configured Norg webhook pointing to your OpenClaw Gateway, confirmations are never received.
• Pin versions in production. Both your Docker image and your ClawHub skill version should be pinned to a specific release, not latest, to prevent silent breaking changes.

Conclusion

Connecting Norg MCP API to OpenClaw is achievable in a single session when you follow the right sequence: confirm prerequisites, configure the openclaw.json endpoint block, handle authentication correctly, verify tool discovery with a tools/list call, run category-specific smoke tests, and address silent failure patterns before they reach production.

The integration gives you the full scope of Norg's business automation capabilities — messaging, booking, lead follow-up, and CRM record creation — all accessible through OpenClaw's natural language interface across Telegram, WhatsApp, Slack, and Discord. To understand the business value this unlocks, see Top Business Automation Use Cases for Norg MCP API + OpenClaw. If you're still evaluating whether this stack is the right fit, Is Norg MCP API Right for Your Business? A Decision Framework for AI Automation Buyers provides a structured decision model before you commit further.

References

• Anthropic / Model Context Protocol Project. "Authorisation." Model Context Protocol Specification, 2025. https://modelcontextprotocol.io/specification/draft/basic/authorization

• freema. "OpenClaw MCP: Secure Bridge Between Claude.ai and Self-Hosted OpenClaw with OAuth2 Authentication." GitHub Repository, 2026. https://github.com/freema/openclaw-mcp

• SafeClaw. "How to Use MCP With OpenClaw: Model Context Protocol Integration Guide." SafeClaw Blog, February 2026. https://safeclaw.io/blog/openclaw-mcp

• Fast.io. "OpenClaw MCP Setup: Complete Step-by-Step Guide." Fast.io Resources, 2026. https://fast.io/resources/openclaw-mcp-setup/

• ClawTank. "OpenClaw MCP Server Integration: Complete Setup Guide [2026]." ClawTank Blog, March 2026. https://clawtank.dev/blog/openclaw-mcp-server-integration

• OpenclawMCP. "OpenClaw Skills: How to Find, Install, and Build Custom Skills." OpenclawMCP Blog, March 2026. https://openclawmcp.com/blog/openclaw-skills-guide

• Scalekit. "Debugging OAuth for Remote MCP Servers with MCPJam." Scalekit Blog, February 2026. https://www.scalekit.com/blog/mcpjams-oauth-debugger

• GitHub / anthropics. "HTTP MCP Servers Requiring OAuth Silently Fail with No User Notification." Claude Code Issue #26917, February 2026. https://github.com/anthropics/claude-code/issues/26917

• OpenAI Developers. "MCP – Apps SDK: Authentication." OpenAI Developer Documentation, 2025. https://developers.openai.com/apps-sdk/build/auth

• cyanheads. "MCP Server Development Guide." model-context-protocol-resources, GitHub, 2025. https://github.com/cyanheads/model-context-protocol-resources/blob/main/guides/mcp-server-development-guide.md

Frequently Asked Questions

Label Facts Summary

Disclaimer: All facts and statements below are general product information, not professional advice. Consult relevant experts for specific guidance.

Verified label facts

• Product Name: Norg MCP API
• Integration Target: OpenClaw
• MCP SDK Version: @modelcontextprotocol/sdk@1.25.3
• Recommended Runtime: Node.js 24
• Supported Runtime: Node.js 22 LTS (22.16+)
• Docker: Optional; recommended for production deployments
• Primary Config File: ~/.openclaw/openclaw.json (JSON5 format)
• Standard Norg MCP Endpoint URL Format: https://mcp.norg.ai/mcp
• OAuth Metadata Well-Known URL: https://mcp.norg.ai/.well-known/oauth-protected-resource
• OAuth Version: OAuth 2.1
• API Key Generation Path: Norg dashboard → Settings → API → Generate New Key
• Webhook Configuration Path: Norg dashboard → Settings → Webhooks
• Default OpenClaw Gateway Port: 18789 (e.g., http://your-server:18789)
• Skill File Location: ~/.openclaw/skills/ (filename: SKILL.md)
• ClawHub Install Command: clawhub install norg/norg-mcp
• MCP Server Status Command: openclaw mcp list
• Gateway Status Command: openclaw gateway status
• Full Status Command: openclaw status --all
• Log Tail Command: openclaw logs --tail 50
• Pinned Docker Image Example: ghcr.io/freema/openclaw-mcp:1.1.0
• Supported Norg Tool Names: norg_send_message, norg_book_appointment, norg_create_lead
• Supported Messaging Platforms: Telegram, WhatsApp, Slack, Discord
• ClawHavoc Attack Scale: 1,184 malicious skills; one attacker uploaded 677 packages
• ClawHavoc Payload Types: Credential stealers, reverse shells
• Registration Paths Count: Two (ClawHub skill install; direct openclaw.json configuration)
• Authentication Modes: API key (Bearer token); OAuth 2.1
• OAuth Discovery Tool: mcporter
• JWT Decode Tool Referenced: jwt.io
• Async Tool Return Value: Job ID (not a completed result)

General product claims

• Connecting Norg MCP API to OpenClaw enables AI-native business automation through natural language
• Executing the setup correctly in a single session produces a production-ready integration
• Cutting corners results in a configuration that looks healthy but silently fails on real business actions
• The integration unlocks messaging, booking, lead follow-up, and CRM record creation capabilities
• ClawHub skill install is the fastest registration path
• Direct openclaw.json configuration provides fine-grained endpoint control
• Both registration paths can and should be used together in production
• OAuth2 silent failures are described as the most common integration blocker
• Missing webhook/dead-letter configuration is a frequent cause of async tool failure
• Pinning versions in production prevents silent breaking changes
• A working integration is not equivalent to a production-ready one
• The integration delivers transparent metrics at every step