Connect an MCP client

Point Claude Desktop, Claude Code, MCP Inspector, or n8n at the Expedify MCP server. All four are verified working.

The server, in one line

• Endpoint: https://api.expedify.ai/v1/mcp
• Transport: Streamable HTTP, JSON-RPC (initialize / tools/list / tools/call).
• Auth: Authorization: Bearer agx_<key> — a scoped API key. The parser is lenient: it accepts Bearer agx_… or a bare agx_….
• Discovery is public: tools/list needs no auth. Execution (tools/call) requires the key → scope / tenant / ACL enforced.
• No SSE / session: GET /v1/mcp returns 405 (we push no server→client notifications). This is MCP-spec-compliant; clients handle it.

Get a key: Settings → API Keys (owner/admin) → scope picker → creates an agx_ key with the {entity}:{read|write} and capability scopes you choose. Prefer least scope — read-only if the agent only queries. Secret keys are shown once; copy at creation.

The key is the org selector

Every agx_ key belongs to exactly one organization and carries its tenant binding + scopes. There's no "pick an org" step in any client — connect with a key from the org you want to reach. A teammate in several orgs adds one MCP server per org, each with that org's key and a distinct name.

---

1. Claude Code (native HTTP — simplest)

Claude Code speaks HTTP MCP directly — no bridge.

claude mcp add --transport http expedify https://api.expedify.ai/v1/mcp \
  --header "Authorization: Bearer agx_<your_key>"

• Default scope is local (this project). Use -s user for all projects.
• Verify: claude mcp list → expedify: … (HTTP) - ✓ Connected.
• Restart the Claude Code session to load it — tools then appear as mcp__expedify__search_contacts, etc.
• Remove with claude mcp remove expedify.

Then just ask: "Use Expedify to search my most recent contacts."

---

2. Claude Desktop (via the mcp-remote bridge)

Claude Desktop's config is stdio-only, so an HTTP server needs the mcp-remote stdio↔HTTP bridge (needs Node / npx).

Config file (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "expedify": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.expedify.ai/v1/mcp",
        "--header", "Authorization:agx_<your_key>"
      ]
    }
  }
}

• Use the bare token (Authorization:agx_…, no Bearer, no space) — mcp-remote has a header-value space-splitting bug; our lenient parser accepts the bare key.
• Merge into existing config (don't clobber other servers). Fully quit (Cmd+Q) and reopen — config is read only at launch.
• Tools show under the 🔨 / connectors indicator.

---

3. MCP Inspector (interactive testing)

npx @modelcontextprotocol/inspector

In the UI: Transport Streamable HTTP · URL https://api.expedify.ai/v1/mcp · Authentication → Bearer Token = agx_<key>. Connect → Tools → List Tools → run search_contacts.

---

4. n8n (MCP Client Tool node)

Point n8n's MCP Client Tool node at https://api.expedify.ai/v1/mcp with header Authorization: Bearer agx_…. (n8n Cloud needs a public URL — a local server won't be reachable.)

---

Troubleshooting

Symptom	Cause / fix
-32001: Missing or malformed Authorization on tools/call	Auth header not attached. Set the Bearer/key in the client's auth field. (tools/list works without it — expected.)
mcp-remote only sends part of the token	The space bug — use the bare token form Authorization:agx_….
Client logs a GET … 405	Expected — no server→SSE stream; spec-compliant, ignore.
Tools don't appear after adding	MCP loads at session/app start — restart Claude Code session / quit-reopen Claude Desktop.
Everything 401 / unreachable	Wrong or rotated key.
A new workflow tool you turned on isn't listed	Reconnect the client — tools/list is read at connect time.

Treat the key like a password

On production the agx_ key is a real credential. Mint least-scope, per-person keys; never share; rotate on offboarding (Settings → API Keys → Rotate), then update the client config.