---
title: "Use Axiom from any MCP client (hosted MCP server)"
description: "Add Axiom's hosted MCP server in any MCP client, authenticate with an Axiom API key, and search the catalog, inspect schemas, read a node's source, invoke nodes and flows, and pin favorites as typed tools — without installing the CLI."
category: guide
surfaces: [cli, http-api]
related: [getting-started/invoke-via-api, guides/api-keys, guides/author-with-claude-code, guides/send-feedback-and-propose, reference/http-api, concepts/sandboxing-and-tenancy]
last_reviewed: 2026-07-17
---

# Use Axiom from any MCP client (hosted MCP server)

Axiom ships a **hosted MCP server** (Model Context Protocol) so an external
agent or user can use Axiom **without installing anything**. Add the server in
any MCP client, authenticate with your Axiom API key, and your agent can search
the catalog, inspect a node or flow's schema, read a node's source code to verify
what it does, invoke it synchronously, and pin favorites that show up as native
typed tools — all over the gateway, scoped to your tenant.

This is a **consume-only** surface. It does not author: you cannot create,
compose, push, or publish from the MCP server. The `axiom` CLI stays the
fully-featured authoring tool (see [Author with Claude Code](./author-with-claude-code.md));
the MCP server is how an agent *uses* what has been published.

## What it is

- **Hosted and zero-install.** The server runs in the Axiom platform behind the
  gateway; your MCP client connects to a URL, not a local process. No CLI, no
  Docker, no SDK in your agent's code.
- **Consume-only.** Search, inspect, read source, invoke, and pin. No authoring
  lifecycle.
- **Authenticated and tenant-scoped.** Your API key authenticates through the
  same gateway every other Axiom client uses (see [API keys](./api-keys.md)).
  Every action is scoped to your tenant: you see public catalog items, your own
  private items, and items you've been granted an entitlement to — never another
  tenant's private data.
- **Typed.** Pinned nodes and flows surface as first-class MCP tools with a
  derived input schema, so your agent calls them with structured arguments
  instead of guessing JSON shapes.

## Add the Axiom MCP server

You need one thing first: an **Axiom API key** — create one in
**Console → API Keys** (see [Create and manage API keys](./api-keys.md)).

Then add the server in a single step. **The only edit you make is replacing
`YOUR_AXIOM_API_KEY` with your key** — everything else is ready to paste as-is.

**Claude Code** — run one command:

```bash
claude mcp add --transport http axiom https://api.axiomide.com/mcp \
  --header "Authorization: Bearer YOUR_AXIOM_API_KEY"
```

**Claude Desktop, Cursor, or any client with an `mcpServers` config file** —
paste this block:

```json
{
  "mcpServers": {
    "axiom": {
      "type": "http",
      "url": "https://api.axiomide.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AXIOM_API_KEY"
      }
    }
  }
}
```

That's it — reload your client and the Axiom tools below appear. Under the hood
the server speaks the MCP Streamable HTTP transport at the `/mcp` path on the
gateway; the gateway validates your key (the same JWT/API-key authorizer the
HTTP API uses) and stamps the authoritative tenant identity, so you only ever
send the `Authorization` header — the server never trusts a tenant the client
supplies.

## The tools

Once connected, `tools/list` advertises the consume surface:

- **`axiom_search`** — search the catalog for **nodes** and **flows**, lexical
  and semantic, tenant-scoped (public + your own + what you're entitled to).
  Results carry the invocable id (`node_id` for nodes, `graph_id` for flows) so
  they pipe straight into inspect or invoke.
- **`axiom_inspect`** — get the compiled input/output **JSON Schema** for a node
  or a flow (the schema a typed invoke payload must satisfy).
- **`axiom_get_source`** — get a node's handler **source code** plus a pointer to
  its **full repository** (`source_url`, pinned to the exact published commit).
  `axiom_inspect` tells you a node's input/output *shape*; `axiom_get_source`
  tells you what it actually *does*, so you can verify a node before invoking it.
  The snippet is the handler body; `source_url` is the escape hatch for reading
  code the handler calls into. For an Instance node the source is the inherited
  generic implementation, and `generic_package` labels its origin.
- **`axiom_invoke`** — synchronously invoke a published **node** or a compiled
  **flow**, resolved by id, alias, or a pinned name. This wraps the existing
  invoke endpoints — it does not create a new invoke path.
- **`axiom_pin` / `axiom_unpin`** — pin a node or a flow as a favorite (one pin
  targets one node *or* one flow). Pins live in a shared store: a pin you make
  from the MCP server is also visible to `axiom list-my-tools` in the CLI, and
  vice versa.
- **`axiom_list_my_tools`** — list your pinned favorites.
- **`axiom_propose`** — propose a **package, node, or flow** that the catalog
  doesn't have yet. Reach for it the moment a task needs an artifact
  `axiom_search` can't find: your proposal is high-signal demand because you hit
  the gap doing real work. It is **propose-only** — an agent can request a
  missing artifact, but filing product bug reports and feature requests stays
  with the human (the CLI's `axiom feedback` and the editor's feedback dialog),
  because those need human repro judgment.

## Pinned tools become typed tools

When you pin a node or a flow, it does not just appear in a list — it shows up
on `tools/list` as a **first-class MCP tool** with a derived `inputSchema`
compiled from the target's proto definition. Your agent can then call it
directly with structured arguments, exactly like a native function. Unpin it and
the tool disappears. (A pinned node's schema comes from its compiled input JSON
Schema; a pinned flow's comes from its on-demand OpenAPI spec.)

## Current limitations

The hosted MCP server is **synchronous only** today. Know these before you rely
on it:

- **Sync-only, ~30s.** `axiom_invoke` waits for a synchronous result and has a
  roughly 30-second budget. There is no async `get_result`, no HITL resume, no
  `recommend`, and no `cancel` yet — those are planned but not available today.
- **A target that can't finish synchronously tells you so — it never hangs or
  silently pauses.** If you invoke something that requires human approval (a
  HITL-bearing target) or that would exceed the sync budget, `axiom_invoke`
  returns a clear, explicit **not-callable** result with the reason
  (`hitl_target` or `exceeds_sync_timeout`). It does **not** return a silent
  `PAUSED` and it does not hang your agent — that is a hard guarantee, not
  best-effort.
- **No authoring.** You cannot create, compose, push, or publish from the MCP
  server. To author, use the `axiom` CLI (see [Author with Claude Code](./author-with-claude-code.md)).
- **Tenant-scoped.** You see only public catalog items, your own, and what you
  are entitled to — the same boundary as the HTTP API (see
  [Sandboxing and tenancy](../concepts/sandboxing-and-tenancy.md)).

## Next steps

- Call a flow the classic way — [Invoke a flow via API](../getting-started/invoke-via-api.md).
- Author and publish nodes and flows with the CLI —
  [Author with Claude Code](./author-with-claude-code.md).
- The HTTP API the MCP server wraps — [HTTP API reference](../reference/http-api.md).