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

# Tools Reference

> All 28 MCP tools — parameters, return shapes, and examples.

All tools communicate via `POST https://mcp.morphic.io/v1/mcp` with `Authorization: Bearer sk_...`.

Response shape: `{"content": [{"type": "text", "text": "<JSON string>"}]}`

***

## Diagnostics

### `ping`

Test the connection. Returns the server name and version.

**Parameters:** none

**Returns:** `pong — morphic-mcp v0.3.5`

***

## Schema Discovery

### `list_entity_types`

List all CRM object types in the workspace. Call this first to discover available slugs.

| Parameter   | Type      | Default | Description    |
| ----------- | --------- | ------- | -------------- |
| `page`      | int ≥ 1   | 1       | Page number    |
| `page_size` | int 1–100 | 50      | Items per page |

```json theme={null}
{
  "items": [
    { "id": "uuid", "slug": "person", "name": "Person", "base_type": "contact", "is_enabled": true }
  ],
  "count": 3,
  "total": 3
}
```

### `get_entity_type_schema`

Get attribute schema for one entity type — field slugs, types, required flags, select options, relation types. Call before `create_entity` or `update_entity`.

| Parameter          | Type   | Required | Description                            |
| ------------------ | ------ | -------- | -------------------------------------- |
| `object_type_slug` | string | Yes      | e.g. `"person"`, `"company"`, `"deal"` |

```json theme={null}
{
  "object_type_slug": "person",
  "count": 8,
  "attributes": [
    { "slug": "email", "name": "Email", "type": "email", "is_required": false },
    { "slug": "stage", "name": "Stage", "type": "select", "options": ["lead", "prospect", "customer"] },
    { "slug": "company", "name": "Company", "type": "relation", "relation_type": "many_to_one" }
  ]
}
```

***

## Entities

### `list_entities`

Paginated list of CRM entities.

| Parameter          | Type      | Default | Description                                                  |
| ------------------ | --------- | ------- | ------------------------------------------------------------ |
| `object_type_slug` | string    | —       | Filter by type: `"person"`, `"company"`, `"deal"`, or custom |
| `search`           | string    | —       | Keyword search across fields                                 |
| `is_archived`      | boolean   | false   | Include archived entities                                    |
| `page`             | int ≥ 1   | 1       |                                                              |
| `page_size`        | int 1–100 | 25      |                                                              |

### `get_entity`

Get a single entity by UUID including full fields, relations, and settings.

| Parameter   | Type | Required |
| ----------- | ---- | -------- |
| `entity_id` | UUID | Yes      |

### `create_entity`

Create a new CRM entity. Use `get_entity_type_schema` first to know valid field slugs.

| Parameter          | Type   | Required | Description                 |
| ------------------ | ------ | -------- | --------------------------- |
| `object_type_slug` | string | Yes      | e.g. `"person"`             |
| `fields`           | object | Yes      | Flat `{"slug": value}` dict |

```json theme={null}
{
  "object_type_slug": "person",
  "fields": { "email": "alice@acme.com", "name": "Alice", "stage": "lead" }
}
```

### `update_entity`

PATCH one or more fields on an existing entity. Only provided fields change.

| Parameter   | Type   | Required |
| ----------- | ------ | -------- |
| `entity_id` | UUID   | Yes      |
| `fields`    | object | Yes      |

### `set_entity_field`

Set a single field by attribute slug. More surgical than `update_entity`.

| Parameter   | Type   | Required |
| ----------- | ------ | -------- |
| `entity_id` | UUID   | Yes      |
| `slug`      | string | Yes      |
| `value`     | any    | Yes      |

### `link_entities`

Create a relation between two entities (e.g. link a person to a company). The attribute slug is resolved to its UUID automatically and cached per session.

| Parameter          | Type   | Required | Description                          |
| ------------------ | ------ | -------- | ------------------------------------ |
| `entity_id`        | UUID   | Yes      | Source entity                        |
| `attribute_slug`   | string | Yes      | Relation attribute, e.g. `"company"` |
| `target_entity_id` | UUID   | Yes      | Target entity                        |

<Note>
  The response includes a `relation_id` UUID. Save it if you may need `unlink_entities` later.
</Note>

### `unlink_entities`

Remove a relation between two entities.

| Parameter     | Type | Required                          |
| ------------- | ---- | --------------------------------- |
| `entity_id`   | UUID | Yes                               |
| `relation_id` | UUID | Yes — returned by `link_entities` |

### `search_entities`

Semantic / vector search using HydraDB. Finds entities by concept rather than exact field match. Returns UUIDs + relevance scores — call `get_entity` to hydrate full records.

| Parameter          | Type     | Default | Description                                                   |
| ------------------ | -------- | ------- | ------------------------------------------------------------- |
| `query`            | string   | —       | Natural language, e.g. `"follow up with Alice about pricing"` |
| `object_type_slug` | string   | —       | Restrict to one type                                          |
| `limit`            | int 1–50 | 10      | Max results                                                   |

```json theme={null}
{ "items": [{ "entity_id": "uuid", "score": 0.92, "title": "Alice Johnson" }], "total": 3 }
```

<Tip>
  If `search_entities` returns empty, the workspace vector index may not be built yet. Use `list_entities` with the `search` parameter instead — it does keyword matching and is always available.
</Tip>

### `archive_entity`

Archive a CRM entity — it's hidden from default listings but recoverable.

| Parameter   | Type    | Default | Description           |
| ----------- | ------- | ------- | --------------------- |
| `entity_id` | UUID    | —       | Entity to archive     |
| `unarchive` | boolean | false   | Set `true` to restore |

### `delete_entity`

Soft-delete an entity. Marks it as deleted and hides it from all queries.

<Warning>
  Prefer `archive_entity` if you might need to recover the entity. Deletion is not easily reversible.
</Warning>

| Parameter   | Type | Required |
| ----------- | ---- | -------- |
| `entity_id` | UUID | Yes      |

***

## Activities & Tasks

Activities are the unified store for logged interactions (emails, calls, meetings) and tasks.

### `list_activities`

| Parameter            | Type   | Description                                           |
| -------------------- | ------ | ----------------------------------------------------- |
| `entity_id`          | UUID   | Filter by linked entity                               |
| `entity_type`        | string | `person` `company` `deal`                             |
| `activity_type`      | string | `email` `meeting` `call` `task` `note` `stage_change` |
| `status`             | string | `not_started` `pending` `completed` `cancelled`       |
| `page` / `page_size` | int    | Pagination (default 1 / 25)                           |

### `get_activity`

| Parameter     | Type | Required |
| ------------- | ---- | -------- |
| `activity_id` | UUID | Yes      |

### `create_activity`

| Parameter       | Type    | Required | Description                                           |
| --------------- | ------- | -------- | ----------------------------------------------------- |
| `activity_type` | string  | Yes      | `task` `email` `call` `meeting` `note` `stage_change` |
| `subject`       | string  | No       | Title / summary                                       |
| `description`   | string  | No       | Full notes                                            |
| `entity_id`     | UUID    | No       | Linked entity                                         |
| `entity_type`   | string  | No       | `person` `company` `deal`                             |
| `due_date`      | ISO8601 | No       | e.g. `"2026-07-01T10:00:00Z"`                         |
| `priority`      | string  | No       | `low` `medium` `high`                                 |
| `status`        | string  | No       | `not_started` `pending` `completed`                   |

### `update_activity`

`activity_id` (UUID, required) + any of: `subject`, `description`, `status`, `priority`, `due_date`, `outcome`

### `complete_task`

Mark a task or activity as completed.

| Parameter     | Type | Required |
| ------------- | ---- | -------- |
| `activity_id` | UUID | Yes      |

***

## Notes

### `list_notes`

| Parameter            | Type   | Description                 |
| -------------------- | ------ | --------------------------- |
| `entity_id`          | UUID   | Filter by entity            |
| `entity_type`        | string | `person` `company` `deal`   |
| `page` / `page_size` | int    | Pagination (default 1 / 25) |

### `create_note`

| Parameter     | Type   | Required | Description                       |
| ------------- | ------ | -------- | --------------------------------- |
| `entity_id`   | UUID   | Yes      | Entity to attach note to          |
| `entity_type` | string | Yes      | `person` `company` `deal`         |
| `body`        | string | Yes      | Note content (markdown supported) |
| `title`       | string | No       | Optional note title               |

### `update_note`

`note_id` (UUID, required) + any of: `body`, `title`, `pinned`

### `delete_note`

<Warning>
  Permanently deletes the note. Cannot be undone.
</Warning>

| Parameter | Type | Required |
| --------- | ---- | -------- |
| `note_id` | UUID | Yes      |

***

## Knowledge Base

### `list_kb_documents`

| Parameter            | Type    | Default | Description                            |
| -------------------- | ------- | ------- | -------------------------------------- |
| `parent_id`          | UUID    | —       | Parent folder; omit for root           |
| `fetch_all`          | boolean | false   | Return all documents across all levels |
| `page` / `page_size` | int     | 1 / 25  |                                        |

### `search_kb_documents`

| Parameter            | Type   | Default         |
| -------------------- | ------ | --------------- |
| `q`                  | string | — (required)    |
| `page` / `page_size` | int    | 1 / 10 (max 50) |

### `get_kb_document`

| Parameter     | Type | Required |
| ------------- | ---- | -------- |
| `document_id` | UUID | Yes      |

### `get_workspace_context`

Fetch the workspace's AI context — a curated text blob for agent priming. **Call this at the start of each session.**

**Parameters:** none

***

## Task Suggestions

### `list_task_suggestions`

AI-generated suggested next actions for a CRM entity.

| Parameter            | Type   | Required | Default     |
| -------------------- | ------ | -------- | ----------- |
| `entity_type`        | string | Yes      |             |
| `entity_id`          | UUID   | Yes      |             |
| `status`             | string | No       | `suggested` |
| `page` / `page_size` | int    | No       | 1 / 10      |

### `accept_task_suggestion`

Accept a suggestion, converting it into a real task activity.

| Parameter       | Type    | Required |
| --------------- | ------- | -------- |
| `suggestion_id` | UUID    | Yes      |
| `due_date`      | ISO8601 | No       |