Skip to main content
Metal exposes the same context layer through two public surfaces. Pick the one that matches how your integration runs. An organization admin enables both from Settings → Organization → API & MCP Access. See Authentication and the Metal MCP server.

​
REST API

The Metal API 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, and activities, and it covers search, lists and taxonomy, enrichment and scoring, workflow automation via API and 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 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 speaks the Model Context Protocol 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 for the category index and the 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 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. To let Metal’s agents call your tools, configure an external MCP server.

​
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. 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. 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.

​
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. 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.
  • Workflow CRM writeback and user edits on CRM-linked records are separate, opt-in paths — not an automatic two-way sync. See CRM integration.
Need a higher rate limit or a second workspace for testing? Email support@metal.ai.