> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose the API or MCP

> When to use the Metal REST API versus the Metal MCP server, how each authenticates, and what a customer-built agent can and cannot do.

Metal exposes the same context layer through two public surfaces. Pick the one that matches how your integration runs.

|              | REST API                                                             | MCP server                                                |
| ------------ | -------------------------------------------------------------------- | --------------------------------------------------------- |
| **Best for** | Server-to-server apps, sync jobs, and your own agents that call HTTP | AI clients such as Claude, ChatGPT, and Cursor            |
| **Auth**     | Organization API key (`x-metal-client-id` + `x-metal-api-key`)       | OAuth for the signed-in Metal user                        |
| **Identity** | Service-level. The key belongs to one organization.                  | Per user. Access matches that person's Metal permissions. |
| **Base URL** | `https://api.metal.ai`                                               | `https://mcp.metal.ai/mcp`                                |

An organization admin enables both from **Settings → Organization → API & MCP Access**. See [Authentication](/authentication) and the [Metal MCP server](/mcp/overview).

## REST API

The [Metal API](/api-reference/introduction) is a JSON REST API under `/v1`. It is **read and write**, not read-only: it can create, read, update, and delete [companies, deals, people](/guides/sync-data), and activities, and it covers [search](/guides/search), lists and taxonomy, enrichment and scoring, workflow automation via API and [webhooks](/guides/webhooks), data, and administration. Documents are searchable and retrievable through the API, but the public API does not upload files — ingest happens in the app or through a connected repository.

The [API reference](/api-reference/introduction#api-sections) owns the section list and endpoint detail. It is generated from the published OpenAPI spec, and only endpoints documented there are supported for customer integrations.

API keys are **server-to-server credentials**. Do not put them in browsers, mobile apps, or an end-user agent that each person runs on their laptop.

## MCP server

The hosted [Metal MCP server](/mcp/overview) speaks the [Model Context Protocol](https://modelcontextprotocol.io) over streamable HTTP. After OAuth sign-in, the client discovers tools with `tools/list`. That live metadata is the source of truth for names, descriptions, and argument schemas.

MCP is built for searching and reading records and running workflows, with authoring tools for lists, dashboards, and workflows. See [Available tools](/mcp/overview#available-tools) for the category index and the [tools reference](/mcp/tools-reference) for per-tool parameters, OAuth scopes, and response shapes.

MCP is **not** a second copy of the REST write surface. It does not create companies or people, edit arbitrary deal fields, or upload documents. Direct writes to companies, deals, or people are limited to **`update_deal_status_and_stage`** (move pipeline stage and/or status) and **`update_list_entry`** write-back to the linked record. See [OAuth scopes](/mcp/tools-reference#oauth-scopes) for the scope requirements.

The server also exposes read-only **resources** and guided **prompts**, and tools return JSON in a text content block. For app-only features and other boundaries that apply to both surfaces, see the list at the end of this page.

To connect Claude, ChatGPT, or Cursor, see [MCP clients](/mcp/clients). To let Metal's agents call *your* tools, configure an [external MCP server](/help/integrations/mcp).

## Permission inheritance

These are different models. Do not treat an API key as "the signed-in end user of my app."

**API key (service).** The key is scoped to one Metal organization. Callers can read and write that organization's API-exposed records. The key does not impersonate each end user of a customer-built application. For how connected file storage affects document access, see [File storage](/help/integrations/file-storage).

**MCP (user).** OAuth is the signed-in Metal member. Tools respect that member's app permissions and granted OAuth scopes. If a user cannot see a document in Metal, an MCP client signed in as that user should not see it either.

**Source-system permissions.** For **Egnyte**, folder and file permission changes sync into Metal as described in [Egnyte access and deletions](/help/integrations/file-storage#egnyte-access-and-deletions). A third-party agent that authenticates with one org API key gets **broad organization access** to API-exposed records, not per-end-user source-system visibility. If you need per-person visibility, have each person connect through MCP with OAuth.

Per-object CRM-style access policies on companies, deals, and people are not a shipped public API feature.

## Auth at a glance

* **API:** create a key in the app. Send `x-metal-client-id` and `x-metal-api-key` on every request. There is no public OAuth or per-end-user token for the REST API.
* **MCP:** no API key. The client opens a browser for Metal OAuth. Admins must enable **Allow access to the Metal MCP server** first.
* **Workflow webhooks:** a per-workflow shared secret or HMAC-SHA256 signature, not the org API key. See [Webhooks](/guides/webhooks).

## Limits and environments

The public API base URL is `https://api.metal.ai` (production). There is no separate public sandbox or test host in the API reference.

Rate limits return `429`. The API applies a per-key (or per signed-in user) budget. MCP applies a separate per-user budget and includes `retry_after` on limit errors. See [Rate limits](/guides/rate-limits). Metal does not publish a latency SLA; treat search, enrichment, and workflow runs as longer than a single-record GET.

## What "build your own on Metal" does not include

State these boundaries in diligence rather than discovering them later:

* Metal is the context layer and system of record. You build agents and integrations **on** that layer. You do not get a self-serve warehouse dump, a raw filesystem mirror of connected storage, or a customer audit-log viewer as part of the public API.
* File ingest is the app or a connected repository, not `POST /v1/documents`.
* Org creation, SSO, and most admin provisioning are Metal-operated, not public API.
* Internal Metal services and engineering tooling are not part of either public surface.
* Canvas workflows are automatable via API, MCP, and webhooks. Productized built-ins such as DDQ Solver stay in the app — `list_workflows` and `run_workflow` cover canvas workflows only. See [Answer DDQs](/help/answer-ddqs).
* Workflow CRM writeback and user edits on CRM-linked records are separate, opt-in paths — not an automatic two-way sync. See [CRM integration](/help/integrations/crm).

Need a higher rate limit or a second workspace for testing? Email [support@metal.ai](mailto:support@metal.ai).


## Related topics

- [Metal MCP server](/mcp/overview.md)
- [Authentication](/authentication.md)
- [External MCP servers](/help/integrations/mcp.md)
- [Quickstart](/quickstart.md)
- [Metal](/index.md)