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

# MCP server

> Connect an MCP-compatible AI client to Default.

Default's MCP server lets an MCP-compatible AI client connect to approved Default data and
tools. Use it when you want an external assistant or custom agent to ask questions about your
workspace through the same permissioned access layer that Default uses for agent workflows.

<Note>
  **MCP access is admin-only.** Every Default MCP tool requires the workspace **admin** role.
  Members and viewers will not see MCP tools even after connecting. If you need access, ask a
  workspace admin.
</Note>

## What you can do

After your client connects, it can discover the tools available to your account and call those
tools through MCP.

Common use cases include:

* inspecting your company and person schema before asking a data question;
* counting or querying company and person records in your Default data model;
* counting or querying Salesforce and HubSpot records through your connected CRM;
* resolving a teammate to their CRM user ID so you can filter records by owner;
* updating a single CRM record through a confirm-before-write flow;
* kicking off an enrichment run for records in a table view or workflow; and
* giving external AI workflows a standard way to talk to Default without copying data out of
  your workspace.

The exact tools you see still depend on your connected integrations and enabled features, but all
of them require the admin role.

## Before you start

You need:

* a Default workspace with MCP access enabled;
* an **admin** account on that workspace;
* an MCP-compatible client that supports remote MCP servers over Streamable HTTP; and
* the Default MCP server URL: `https://mcp.default.com/mcp`.

<Tip>
  If your client asks for a server URL, use the Default MCP endpoint: `https://mcp.default.com/mcp`.
</Tip>

## Connect your MCP client

Every MCP client has its own setup flow, but the connection pattern is the same.

<Steps>
  <Step title="Open your MCP client settings">
    In your AI tool or agent platform, open the area for adding a new MCP server.
  </Step>

  <Step title="Add the Default MCP server URL">
    Choose a remote or Streamable HTTP MCP server, then enter the Default MCP endpoint:
    `https://mcp.default.com/mcp`.
  </Step>

  <Step title="Sign in">
    Follow your client's browser-based authorization prompt to sign in to Default. Sign-in is
    browser-based OAuth — there is no separate access-token, bearer-token, or API-key method. The
    signed-in user must be an admin.
  </Step>

  <Step title="Discover available tools">
    Ask your client to list or refresh MCP tools. The available tools are filtered by your role,
    connected integrations, and enabled workspace features. Compatible clients refresh this list
    automatically when Default signals that tool access changed.
  </Step>

  <Step title="Ask a workspace question">
    Start with a specific question, such as "What company fields can I query?" or "How many
    companies match this filter?" Your client may call Default tools automatically when it
    decides they are relevant.
  </Step>
</Steps>

## Available tools

The tools below are generally available on Default's MCP server today. **All of them require the
admin role** — there is no member-level MCP access. Read tools return data; write and run tools
change data or start jobs, so treat them accordingly.

<Info>
  Some data-import tooling — file uploads, CSV-to-object ingestion, and segment management — is
  rolling out behind a feature flag and is **not yet generally available**. It is intentionally
  omitted here and may not appear in your client's tool list.
</Info>

### System

| Tool          | Type | What it does                                                                                               |
| ------------- | ---- | ---------------------------------------------------------------------------------------------------------- |
| `system_ping` | Read | Confirms the MCP service is reachable and that its authenticated link to Default's API works.              |
| `calculate`   | Read | Evaluates an arithmetic expression and returns the exact result — percentages, ratios, sums, and the like. |

<Accordion title="calculate details">
  Supports `+ - * / % ^`, parentheses, unary minus, and the functions `abs`, `round`, `floor`,
  `ceil`, `sqrt`, `min`, `max`, and `pow`. Numbers and operators only — no variables. Example:
  `(150000 * 0.85) / 12`.
</Accordion>

### Company & person data

These tools read your Default data model (the company and person records that fill your Tables).

| Tool          | Type | What it does                                                                                        |
| ------------- | ---- | --------------------------------------------------------------------------------------------------- |
| `data_schema` | Read | Returns the field descriptors for `person` or `company` records so you know what you can filter on. |
| `data_count`  | Read | Returns an aggregate count of `person` or `company` records, with optional schema-backed filters.   |
| `data_query`  | Read | Returns `person` or `company` rows with required pagination and a schema-backed field allowlist.    |

<Tip>
  Call `data_schema` first so your client knows which fields exist before it filters or sorts with
  `data_count` or `data_query`.
</Tip>

### CRM (Salesforce & HubSpot)

These tools read and write through your connected CRM integration. The relevant integration
(Salesforce or HubSpot) must be connected and synced.

| Tool                             | Type  | What it does                                                                                                 |
| -------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------ |
| `crm_schema`                     | Read  | Returns provider-aware field descriptors for a Salesforce or HubSpot object.                                 |
| `crm_count`                      | Read  | Returns an aggregate count for a CRM object, with optional schema-backed filters.                            |
| `crm_query`                      | Read  | Returns CRM rows with required pagination and a schema-backed field allowlist.                               |
| `crm_actor`                      | Read  | Returns the signed-in user's own Salesforce / HubSpot user IDs, for owner-filtered queries.                  |
| `integration_user_mappings_list` | Read  | Lists CRM user mappings for the org; filter by email or name to resolve a teammate before an owner filter.   |
| `crm_write`                      | Write | Updates fields on a single CRM record. Two-step: preview first, then re-call with `confirm: true` to commit. |

<Accordion title="How crm_write confirmation works">
  `crm_write` never changes data on the first call. Call it without `confirm` (or with `confirm:
    	false`) to get a `pending_confirmation` preview of the resolved change, surface that preview to
  the operator, and only re-call with `confirm: true` after they approve. Field ids are validated
  against `crm_schema`.
</Accordion>

### Enrichment

| Tool             | Type | What it does                                                                                     |
| ---------------- | ---- | ------------------------------------------------------------------------------------------------ |
| `enrichment_run` | Run  | Starts an enrichment job for records in a table view or workflow, using a provider or waterfall. |

<Accordion title="enrichment_run details">
  Either pass explicit `record_ids`, or omit them and set a `mode` (for example `all` or
  `all_empty_cells`) to resolve the record set from the view. This starts a job — it does not return
  enriched values inline.
</Accordion>

## Example prompts

Concrete, specific prompts work best. Name the object, the fields, and any filter, owner, or
timeframe you care about, and the client will pick the right tools.

**Explore what's there**

* "Which company fields can I filter and sort on?"
* "Show me the schema for person records, then list the ten most recently created."

**Count and segment**

* "How many companies were created in the last 30 days?"
* "How many person records are missing a job title?"

**Query your CRM**

* "List Salesforce opportunities in the 'Negotiation' stage, sorted by amount, and page through them."
* "Count HubSpot companies in the technology industry with more than 500 employees."

**Filter by owner**

* "Find my Salesforce user ID, then list the accounts I own."
* "Look up Jordan Lee's HubSpot owner ID and count the deals they own."

**Run enrichment**

* "Enrich every person in my 'Inbound leads' view that's missing a company name."

**Do the math**

* "For companies in that view, what's the average deal size? Use the calculator for the exact number."

**Update a record (with confirmation)**

* "Set the lifecycle stage to 'Customer' on this HubSpot company — show me the change to approve before writing."

## How access works

Default only exposes tools that your account is allowed to discover and call.

| Access layer           | What it controls                                                                        |
| ---------------------- | --------------------------------------------------------------------------------------- |
| Workspace enablement   | Whether MCP access is available for your workspace.                                     |
| Authentication         | Whether the request comes from a Default user signed in through browser-based OAuth.    |
| Role                   | MCP tools require the **admin** role; members and viewers cannot use them.              |
| Enabled features       | Feature-gated tool families appear only while enabled for your workspace.               |
| Connected integrations | Which external systems and records Default can use to answer (for example CRM queries). |

If a tool is not allowed for your account, it may not appear in your client's tool list.
Default re-checks current access whenever a tool is called, so a tool cached by a client cannot be
used after its access is revoked.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No tools appear after I connect">
    Confirm MCP access is enabled for your workspace and that you are signed in as an admin —
    members and viewers do not see MCP tools. Then refresh the tool list in your client.
    Available tools also depend on your connected integrations.
  </Accordion>

  <Accordion title="A newly enabled tool does not appear">
    Refresh the MCP server in your client. Default sends the standard
    `notifications/tools/list_changed` notification when the client opens its update channel, but some
    clients keep an older tool cache or do not implement automatic list refresh. If a refresh does not
    issue a new tool-list request, disconnect and reconnect the MCP server.
  </Accordion>

  <Accordion title="A listed tool says disabled or not found">
    Your client likely cached a tool that is no longer enabled. Default enforces current access at
    execution time even when the client's display is stale. Refresh the MCP tool list to remove it.
  </Accordion>

  <Accordion title="My client says the server is unauthorized">
    Sign in again to refresh your session. If the error continues, confirm that your client is pointed
    at the Default MCP server URL and that you completed the browser-based sign-in as an admin.
  </Accordion>

  <Accordion title="A tool appears but cannot answer my question">
    Add more context to your prompt. Include the object, field, timeframe, owner, or filter you want
    the tool to use. If the data comes from an integration, confirm that integration is connected and
    synced.
  </Accordion>

  <Accordion title="A browser-based client gets an origin error">
    Ask your Default admin or implementation team to confirm the client origin is allowed for
    your workspace's MCP configuration.
  </Accordion>
</AccordionGroup>

## For custom client builders

Custom clients should connect to Default's remote MCP endpoint over Streamable HTTP, then use
standard MCP requests to discover and call tools:

1. Connect to the Default MCP endpoint: `https://mcp.default.com/mcp`.
2. Complete the browser-based OAuth sign-in as an admin user (there is no access-token or
   service-token flow).
3. Send `initialize`, then send `notifications/initialized`.
4. Open authenticated `GET /mcp` with `Accept: text/event-stream` to receive server notifications.
5. Call `tools/list` to discover available tools.
6. When `notifications/tools/list_changed` arrives, call `tools/list` again and replace the cached
   tool schemas.
7. Call `tools/call` with the selected tool name and arguments. Include the bearer credential on
   every request; Default's MCP endpoint does not require worker-affine session state.

<Note>
  Default's MCP server currently exposes tools. Resources and prompts may not be available from this
  endpoint unless your workspace has been explicitly configured for them.
</Note>

```json Example tools/call request theme={null}
{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "tools/call",
	"params": {
		"name": "data_count",
		"arguments": {
			"object": "company"
		}
	}
}
```

The response includes MCP content and, when available, structured output that your client can
render as text, tables, or another UI.