MCP tools reference - Metal Docs

This page documents the tools exposed by the Metal MCP server at https://mcp.metal.ai/mcp. Your AI client discovers these tools automatically after OAuth sign-in. Use this reference when building integrations, debugging tool calls, or understanding what data comes back.

Tool availability depends on your OAuth scopes and organization settings. If a tool is missing or returns insufficient scope, your connection may not have been granted that permission.

How tool calls work

Metal implements the Model Context Protocol over streamable HTTP. Your client sends JSON-RPC messages to /mcp; each tools/call request names a tool and passes a JSON arguments object.

Tool discovery and schemas

After OAuth sign-in, your MCP client discovers the exact live tool metadata from the server with the MCP tools/list method. That response is the source of truth for each tool’s description, inputSchema, and safety annotations. Use this page as the human-readable reference for tool behavior, common parameters, scopes, response shapes, and examples. If you are generating code, validating arguments, or debugging a client integration, inspect the live inputSchema from tools/list instead of hardcoding this page’s parameter tables. When you inspect a call in a client like Cursor, you typically see:

{
  "name": "search_companies",
  "arguments": {
    "query": "Acme Industrial",
    "pageSize": 5
  }
}

Response format

Every tool returns a text content block containing JSON (or a plain-text error message). Successful responses fall into three shapes: Single record — the JSON object is the payload directly:

{
  "id": "507f1f77bcf86cd799439011",
  "canonicalName": "Acme Industrial",
  "sector": "Industrials"
}

Paginated list — results are wrapped in data and pagination:

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "canonicalName": "Acme Industrial"
    }
  ],
  "pagination": {
    "paginationMode": "page",
    "page": 1,
    "limit": 20,
    "resultCount": 1,
    "totalCount": 47,
    "totalPages": 3,
    "hasMore": true
  }
}

Document search — data contains grouped documents and excerpts instead of a flat array:

{
  "data": {
    "documents": [
      {
        "document": {
          "id": "507f1f77bcf86cd799439011",
          "displayName": "Acme CIM 2024",
          "sourceLinkMarkdown": "[Acme CIM 2024 p. 12](https://app.metal.ai/entities/507f1f77bcf86cd799439011)"
        },
        "excerpts": [
          {
            "page": 12,
            "text": "Revenue grew 18% year-over-year...",
            "relevance": 0.92,
            "sourceLinkMarkdown": "[Acme CIM 2024 p. 12](https://app.metal.ai/entities/507f1f77bcf86cd799439011)"
          }
        ]
      }
    ],
    "citationGuidance": "Always include each excerpt's sourceLinkMarkdown when presenting facts from search_documents."
  },
  "pagination": {
    "paginationMode": "page",
    "page": 1,
    "limit": 20,
    "resultCount": 3,
    "documentCount": 1,
    "hasMore": false
  }
}

Errors

When a call fails validation or the backend returns an error, the tool result is marked as an error and the text content holds a message:

query is required for search_companies; use list_companies for filter-only browsing

Common error patterns:

Message	Cause
`insufficient scope: requires read:companies`	OAuth token lacks the scope for that tool
`unauthenticated request`	Session expired or connection not signed in
`Rate limit exceeded`	Per-user rate limit hit; JSON body includes `retry_after` seconds

Rate-limit errors return structured JSON in the error text:

{
  "error": "Rate limit exceeded",
  "limit": 60,
  "remaining": 0,
  "retry_after": 42
}

Pagination

Most list and search tools use page mode (paginationMode: "page"). Pass page (default 1) and pageSize (default 20, max 50). Continue while hasMore is true. get_list_entries uses cursor mode (paginationMode: "cursor"). Pass nextToken from the prior response to fetch the next page. Field definitions for each resource type are available as MCP resources — see Resources below.

OAuth scopes

Tools require OAuth scopes granted during sign-in:

Scope	Tools
`read:companies`	`list_companies`, `search_companies`, `list_company_tags`, `get_company`, `get_custom_field_definitions` for company fields
`read:documents`	`get_document`, `search_documents`
`read:people`	`search_people`, `get_person`
`read:deals`	`search_deals`, `get_deal`, `get_custom_field_definitions` for deal fields
`read:users`	`search_users`, `get_current_user`, `get_user`
`read:teams`	`list_teams`, `get_team`
`read:lists`	`list_lists`, `get_list`, `get_list_entries`
`read:activities`	`get_activities`, `get_activity`
`read:workflows`	Workflow read and inspect tools
`read:screenings`	`search_screenings`, `get_screening`, `get_screening_scores`
`read:scores`	`list_scoring_frameworks`, `get_scoring_framework`
`write:workflow_runs`	`run_workflow`, `review_workflow_hitl_step`
`write:workflows`	Workflow authoring tools

Companies

`search_companies`

Search companies by name. Uses hybrid semantic + keyword matching on company names. Scope: read:companies

Parameter	Type	Required	Description
`query`	string	Yes	Company name or alias to search
`sector`	string	No	Filter by sector
`subsector`	string	No	Filter by subsector
`tagIds`	string[]	No	Company tag IDs (resolve with `list_company_tags`)
`customFilters`	object[]	No	Org-defined custom company field filters (discover with `get_custom_field_definitions`)
`assigneeIds`	string[]	No	Metal user IDs assigned to the company
`assignedToMe`	boolean	No	Restrict to companies assigned to you
`assignedTeamIds`	string[]	No	Team IDs (resolve with `list_teams`)
`assignedTeamStatuses`	string[]	No	Team coverage labels (e.g. Mine/Learn, Monitor)
`city`, `state`, `country`	string	No	Location filters
`page`, `pageSize`	integer	No	Pagination

{
  "name": "search_companies",
  "arguments": {
    "query": "Acme",
    "sector": "Industrials",
    "pageSize": 5
  }
}

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "canonicalName": "Acme Industrial",
      "sector": "Industrials",
      "subsector": "Industrial Automation",
      "shortDescription": "Provider of factory automation systems."
    }
  ],
  "pagination": {
    "paginationMode": "page",
    "page": 1,
    "limit": 5,
    "resultCount": 1,
    "hasMore": false
  }
}

`list_companies`

Browse companies with structured filters only — no text query. Use this for sector, tag, team, or location lists. Scope: read:companies Same filter parameters as search_companies except query is not accepted. At least one filter is required.

{
  "name": "list_companies",
  "arguments": {
    "sector": "Healthcare",
    "assignedToMe": true,
    "pageSize": 20
  }
}

`list_company_tags`

List company tags so you can pass exact IDs to tagIds filters. Scope: read:companies

Parameter	Type	Description
`page`, `pageSize`	integer	Optional pagination

Returns a paginated list of tag objects with id and name.

`get_company`

Get a full company profile by ID. Scope: read:companies

Parameter	Type	Required
`id`	string	Yes — 24-character hex ObjectID

{
  "name": "get_company",
  "arguments": {
    "id": "507f1f77bcf86cd799439011"
  }
}

Returns an enriched company record including enrichedValues with citations. Field keys match the metal://fields/companies resource.

Custom fields

`get_custom_field_definitions`

List org-defined custom field definitions for companies and deals. Use this before passing customFilters to search_companies, list_companies, or search_deals, and to interpret values in the custom map returned by company and deal tools. Scope: read:companies for company fields; read:deals for deal fields.

Parameter	Type	Description
`resourceTypes`	string[]	Optional resource types to return: `companies`, `deals`. Defaults to every supported resource type your token can read.

Each definition includes the field key, display name, type, whether it can be used in customFilters, and supported operators. String fields support eq, neq, in, and nin; number fields support eq, neq, gt, gte, lt, lte, in, and nin; boolean fields support eq and neq; date fields support range operators gt, gte, lt, and lte.

Documents

`search_documents`

Search document content or list documents by type and date. Scope: read:documents

Parameter	Type	Description
`query`	string	Content search text. Pass `""` for filter-only listing
`documentType`	string	Filter by type (see `metal://document-types`)
`companyIds`	string[]	Restrict to documents linked to these companies
`documentIds`	string[]	Restrict to specific document IDs
`sort`	string	`latest` or `oldest` — used when `query` is empty
`page`, `pageSize`	integer	Pagination over matching excerpts

Content search — find text inside documents:

{
  "name": "search_documents",
  "arguments": {
    "query": "unit economics SaaS",
    "pageSize": 10
  }
}

Filter-only listing — recent CIMs without relevance ranking:

{
  "name": "search_documents",
  "arguments": {
    "query": "",
    "documentType": "CIM (Confidential Information Memorandum)",
    "sort": "latest",
    "pageSize": 10
  }
}

Always cite sourceLinkMarkdown from each excerpt when presenting facts.

`get_document`

Get extracted text from a document by line number. Scope: read:documents

Parameter	Type	Description
`id`	string	Document ID (required)
`startLine`	integer	First line to return (default `1`)
`endLine`	integer	Last line (default start + 499; max 500 lines per call)

{
  "name": "get_document",
  "arguments": {
    "id": "507f1f77bcf86cd799439011",
    "startLine": 1
  }
}

{
  "document": {
    "id": "507f1f77bcf86cd799439011",
    "displayName": "Acme CIM 2024",
    "documentType": "CIM (Confidential Information Memorandum)",
    "sourceLinkMarkdown": "[Acme CIM 2024](https://app.metal.ai/entities/507f1f77bcf86cd799439011)"
  },
  "content": "     1|Executive Summary\n     2|Acme Industrial is a leading...",
  "lines": [
    { "line": 1, "text": "Executive Summary", "page": 1 },
    { "line": 2, "text": "Acme Industrial is a leading...", "page": 1 }
  ],
  "startLine": 1,
  "endLine": 500,
  "returnedLines": 2,
  "reachedEof": true,
  "status": "EOF - End of document",
  "citationGuidance": "When presenting information from this document, include the source markdown link from document.sourceLinkMarkdown."
}

When reachedEof is false, call again with startLine set to nextLine.

People

`search_people`

Search contacts by name, title, company, or email. Scope: read:people

Parameter	Type	Description
`query`	string	Search text
`assigneeIds`	string[]	Filter by assigned Metal user IDs
`assignedToMe`	boolean	Contacts assigned to you
`contactType`	string	Advisor, Banker, Board, Executive, Investor, Lender, Operational, Other
`priority`	integer	1 (highest) through 5 (lowest)
`page`, `pageSize`	integer	Pagination

`get_person`

Get a full contact profile by ID. Scope: read:people

Parameter	Type	Required
`id`	string	Yes

Deals

`search_deals`

Search or filter deals. query is optional for filter-only searches. Scope: read:deals

Parameter	Type	Description
`query`	string	Deal name, company, or description text
`companyIds`	string[]	Target company IDs
`sourceCompanyIds`	string[]	Sourcing bank or advisor company IDs
`ownerUserIds`	string[]	Deal owner user IDs
`ownerTeamIds`	string[]	Deal owner team IDs
`status`, `stage`	string	Internal enum or org CRM label
`customFilters`	object[]	Org-defined custom deal field filters (discover with `get_custom_field_definitions`)
`createdAfter`, `createdBefore`	string	RFC3339 timestamps
`updatedAfter`, `updatedBefore`	string	RFC3339 timestamps
`closeAfter`, `closeBefore`	string	RFC3339 timestamps
`page`, `pageSize`	integer	Pagination

Resolve company names with search_companies, user names with search_users, and team IDs with list_teams before passing ID filters.

{
  "name": "search_deals",
  "arguments": {
    "companyIds": ["507f1f77bcf86cd799439011"],
    "status": "Active",
    "pageSize": 10
  }
}

`get_deal`

Get a full deal record by ID. Scope: read:deals

Parameter	Type	Required
`id`	string	Yes

Users and teams

`get_current_user`

Return the authenticated user and connected organization. No arguments. Scope: read:users

{
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "you@firm.com",
    "firstName": "Alex",
    "lastName": "Smith"
  },
  "org": {
    "id": "507f1f77bcf86cd799439012",
    "name": "Example Capital",
    "displayName": "Example Capital Partners"
  }
}

`search_users`

Search Metal users by name or email. query is required. Scope: read:users

`get_user`

Get a user by ID. Scope: read:users

Parameter	Type	Required
`id`	string	Yes

`list_teams`

List teams in your organization. Returns team names and IDs for use in deal and company filters. Scope: read:teams

`get_team`

Get a team by ID. Scope: read:teams

Parameter	Type	Required
`id`	string	Yes

Lists

`list_lists`

List resource lists in your organization. Scope: read:lists

Parameter	Type	Description
`resourceType`	string	Optional filter: `company`, `person`, `deal`, etc.
`page`, `pageSize`	integer	Pagination

`get_list`

Get a list’s metadata and column schema by ID. Does not include row data — use get_list_entries. Scope: read:lists

Parameter	Type	Required
`id`	string	Yes

`get_list_entries`

Page through list rows with cursor pagination. Scope: read:lists

Parameter	Type	Description
`id`	string	List ID (required)
`pageSize`	integer	Rows per page (default 50, max 50)
`nextToken`	string	Token from prior response

{
  "data": [
    {
      "id": "entry-id",
      "resourceId": "507f1f77bcf86cd799439011",
      "values": { "Priority": "High" }
    }
  ],
  "pagination": {
    "paginationMode": "cursor",
    "limit": 50,
    "resultCount": 1,
    "hasMore": true,
    "nextToken": "eyJwYWdlIjoyfQ=="
  }
}

Activities

`get_activities`

Get meetings, calls, and interactions for a company. Scope: read:activities

Parameter	Type	Required	Description
`participantId`	string	Yes	Company ID
`page`, `pageSize`	integer	No	Pagination

`get_activity`

Get a single activity by ID, including participants, linked deals, and attached documents. Scope: read:activities

Parameter	Type	Required
`id`	string	Yes

Screenings and scoring

`search_screenings`

List or filter CIM screenings. Free-text query is not supported — use structured filters. Scope: read:screenings

Parameter	Type	Description
`companyIds`, `dealIds`, `dataEntityIds`	string[]	Link filters
`status`, `statuses`	string	Screening status
`sector`, `subsector`, `industry`	string	Taxonomy filters
`createdAfter`, `createdBefore`	string	RFC3339
`updatedAfter`, `updatedBefore`	string	RFC3339
`sortBy`	string	`createdAt`, `updatedAt`, `companyName`, `revenue`, `ebitda`
`sortOrder`	string	`asc` or `desc`
`page`, `pageSize`	integer	Pagination

`get_screening`

Get a screening by ID, including financials, analysis, and validation metadata. Scope: read:screenings

Parameter	Type	Required
`id`	string	Yes

`get_screening_scores`

Get score records for a screening. Scope: read:screenings and read:scores

Parameter	Type	Description
`screeningId`	string	Required
`framework`	string	Optional filter by framework name

`list_scoring_frameworks`

List scoring frameworks visible to your organization. Scope: read:scores

Parameter	Type	Description
`entityType`	string	`company`, `person`, `deal`, or `screening`
`includeStandard`	boolean	Append standard frameworks
`onlyStandard`	boolean	Return only standard frameworks

`get_scoring_framework`

Get a framework definition by ID. Standard frameworks use IDs like standard:Porter's Five Forces. Scope: read:scores

Parameter	Type	Required
`id`	string	Yes

Workflows

Workflow tools split into read/inspect, run, and authoring groups.

Read and inspect

Scope: read:workflows

Tool	Purpose
`list_workflows`	Discover workflow IDs (`page`, `pageSize`)
`get_workflow`	Workflow definition overview (`workflowId`, optional `version`, `fieldPath`)
`get_workflow_step`	Full step definition (`workflowId`, `stepId`, optional `childStepId`, `version`)
`list_workflow_runs`	Find runs (`resourceType`, `resourceId`, `statuses`, date filters, pagination)
`get_workflow_run`	Run status and outputs (`workflowRunId`, `view` or `fieldPath`)
`get_workflow_run_step`	Step evidence (`workflowRunId`, `stepId`, optional `itemIndex`, `childStepId`, `view`)

view shortcuts for get_workflow_run: overview, steps, outputs, errors, failures, artifacts, citations, full. Do not pass view and fieldPath together. view shortcuts for get_workflow_run_step: overview, outputs, transcript, toolCalls, artifacts, errors, iteratorItems, hitl, execution, full.

{
  "name": "get_workflow",
  "arguments": {
    "workflowId": "507f1f77bcf86cd799439011",
    "fieldPath": "inputSchema"
  }
}

Run workflows

Scope: write:workflow_runs

`run_workflow`

Start a workflow run. Inspect inputSchema with get_workflow first and supply every required field in input.

Parameter	Type	Required	Description
`workflowId`	string	Yes	24-character hex ID
`input`	object	No	Workflow inputs matching `inputSchema`
`visibility`	string	No	Run visibility override

{
  "name": "run_workflow",
  "arguments": {
    "workflowId": "507f1f77bcf86cd799439011",
    "input": {
      "companyId": "507f1f77bcf86cd799439012"
    }
  }
}

The response includes immediate run status and polling guidance. Call get_workflow_run when the run completes to read bounded outputs.

`review_workflow_hitl_step`

Approve or reject a human-in-the-loop step. Inspect the pending step with get_workflow_run_step using view: "hitl" first.

Parameter	Type	Required	Description
`workflowRunId`	string	Yes	Run ID
`stepId`	string	Yes	HITL step ID
`action`	string	Yes	`approve` or `reject`
`approvedItemIds`	string[]	No	Required item IDs when approving structured reviews

Authoring

Scope: write:workflows These tools create and edit draft workflows:

Tool	Purpose
`create_workflow`	Create a new draft workflow
`update_workflow_details`	Update name, description, and metadata
`configure_workflow_input`	Set input schema and UI schema
`configure_workflow_trigger`	Configure how the workflow starts
`configure_workflow_output`	Configure output sections
`add_workflow_step`	Add a step to the definition
`update_workflow_step`	Update an existing step
`delete_workflow_step`	Remove a step
`move_workflow_step`	Reorder steps
`list_workflow_building_options`	List valid step types, triggers, and configuration options

Call list_workflow_building_options before authoring to discover allowed step types and field shapes. Authoring tool inputs are validated server-side; validation errors return structured JSON in the error text.

Resources

Your client can read MCP resources alongside tools. These are read-only catalogs — not tool calls.

URI	Description
`metal://document-types`	Valid `documentType` values for `search_documents`
`metal://resource-types`	Entity types, associated tools, and relationships
`metal://fields/companies`	Field keys returned by company tools
`metal://fields/people`	Field keys returned by people tools
`metal://fields/deals`	Field keys returned by deal tools
`metal://fields/documents`	Field keys returned by document tools
`metal://fields/activities`	Field keys returned by activity tools

Prompts

The server also exposes guided prompts your client can invoke:

Prompt	Arguments
`company_due_diligence`	`company_name` (required), `focus_areas`
`deal_analysis`	`deal_name` (required)
`sector_landscape`	`sector` (required), `region`
`document_research`	`topic` (required), `document_type`
`contact_network`	`company_name` (required), `role_filter`

Prompts orchestrate multiple tool calls — they do not return data directly.

Tool index

All 44 tools (alphabetical)

add_workflow_step · configure_workflow_input · configure_workflow_output · configure_workflow_trigger · create_workflow · delete_workflow_step · get_activities · get_activity · get_company · get_current_user · get_custom_field_definitions · get_deal · get_document · get_list · get_list_entries · get_person · get_scoring_framework · get_screening · get_screening_scores · get_team · get_user · get_workflow · get_workflow_run · get_workflow_run_step · get_workflow_step · list_companies · list_company_tags · list_lists · list_scoring_frameworks · list_teams · list_workflow_building_options · list_workflow_runs · list_workflows · move_workflow_step · review_workflow_hitl_step · run_workflow · search_companies · search_deals · search_documents · search_people · search_screenings · search_users · update_workflow_details · update_workflow_step

​How tool calls work

​Tool discovery and schemas

​Response format

​Errors

​Pagination

​OAuth scopes

​Companies

​search_companies

​list_companies

​list_company_tags

​get_company

​Custom fields

​get_custom_field_definitions

​Documents

​search_documents

​get_document

​People

​search_people

​get_person

​Deals

​search_deals

​get_deal

​Users and teams

​get_current_user

​search_users

​get_user

​list_teams

​get_team

​Lists

​list_lists

​get_list

​get_list_entries

​Activities

​get_activities

​get_activity

​Screenings and scoring

​search_screenings

​get_screening

​get_screening_scores

​list_scoring_frameworks

​get_scoring_framework

​Workflows

​Read and inspect

​Run workflows

​run_workflow

​review_workflow_hitl_step

​Authoring

​Resources

​Prompts

​Tool index

How tool calls work

Tool discovery and schemas

Response format

Errors

Pagination

OAuth scopes

Companies

`search_companies`

`list_companies`

`list_company_tags`

`get_company`

Custom fields

`get_custom_field_definitions`

Documents

`search_documents`

`get_document`

People

`search_people`

`get_person`

Deals

`search_deals`

`get_deal`

Users and teams

`get_current_user`

`search_users`

`get_user`

`list_teams`

`get_team`

Lists

`list_lists`

`get_list`

`get_list_entries`

Activities

`get_activities`

`get_activity`

Screenings and scoring

`search_screenings`

`get_screening`

`get_screening_scores`

`list_scoring_frameworks`

`get_scoring_framework`

Workflows

Read and inspect

Run workflows

`run_workflow`

`review_workflow_hitl_step`

Authoring

Resources

Prompts

Tool index