---
title: "MCP form tools — HyperCRM"
description: "The five MCP tools for intake and consent forms and their submissions: every argument, an example call, and why the whole domain is owner-only including reads."
canonical: "https://hypercrm.app/docs/mcp/forms"
lang: "en"
updated: "2026-07-26"
---

_MCP reference / Forms_

# Form tools

Five tools covering intake and consent forms and their submissions. The whole domain is owner-only, reads included, because submissions carry clinical answers.

[Start the free trial](/dashboard) · [All 60 tools](/docs/mcp/tools)

## How to read this

Each tool below lists its arguments exactly as the input schema declares them — the type, whether it is required, and the permitted values where the schema fixes them. There are no argument descriptions: the schemas carry types, not prose, and inventing a sentence per argument would be writing fiction about a contract.

`practiceId` is never an argument. It comes from your token, and the write paths strip it if a client sends one anyway.

Every example is a complete `tools/call` request with this tool's required arguments filled in. Errors are returned inside a `200` response with `isError` set — see the [MCP overview](/docs/mcp) for that envelope, and the [full catalogue](/docs/mcp/tools) for every tool at a glance.

Intake and consent forms. Every tool here is owner-only, reads included, because submissions carry clinical answers.

### list_forms

_Read-only, Owner only_

List the practice's intake and consent forms.

**Example call**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_forms",
    "arguments": {}
  }
}
```

**Result**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}
```

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `forbidden` | 403 | The caller is not an owner of the practice. |
| `unauthorized` | 401 | The bearer token is missing, invalid or expired. |

### get_form

_Read-only, Owner only_

Read one form with its field definitions.

**Arguments**

| Tool | Type | Required? |
| --- | --- | --- |
| `formId` | `string` | Required |

**Example call**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_form",
    "arguments": {
      "formId": "0f1c7a2e-...."
    }
  }
}
```

**Result**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}
```

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `validation_failed` | 400 | An argument is missing, of the wrong type, or outside its allowed values. |
| `not_found` | 404 | The id does not exist in your practice. A malformed id looks identical. |
| `forbidden` | 403 | The caller is not an owner of the practice. |
| `unauthorized` | 401 | The bearer token is missing, invalid or expired. |

### list_form_submissions

_Read-only, Owner only_

List every submission for a form, newest first.

**Arguments**

| Tool | Type | Required? |
| --- | --- | --- |
| `formId` | `string` | Required |
| `status` | `all` \\| `submitted` \\| `pending` | Optional |
| `page` | `integer` | Optional |
| `pageSize` | `integer` | Optional |

**Example call**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_form_submissions",
    "arguments": {
      "formId": "0f1c7a2e-...."
    }
  }
}
```

**Result**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}
```

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `validation_failed` | 400 | An argument is missing, of the wrong type, or outside its allowed values. |
| `not_found` | 404 | The id does not exist in your practice. A malformed id looks identical. |
| `forbidden` | 403 | The caller is not an owner of the practice. |
| `unauthorized` | 401 | The bearer token is missing, invalid or expired. |

### get_form_submission

_Read-only, Owner only_

Read a single submission and its answers.

**Arguments**

| Tool | Type | Required? |
| --- | --- | --- |
| `formId` | `string` | Required |
| `submissionId` | `string` | Required |

**Example call**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_form_submission",
    "arguments": {
      "formId": "0f1c7a2e-....",
      "submissionId": "0f1c7a2e-...."
    }
  }
}
```

**Result**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the requested records" }
    }
  }
}
```

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `validation_failed` | 400 | An argument is missing, of the wrong type, or outside its allowed values. |
| `not_found` | 404 | The id does not exist in your practice. A malformed id looks identical. |
| `forbidden` | 403 | The caller is not an owner of the practice. |
| `unauthorized` | 401 | The bearer token is missing, invalid or expired. |

### write_form

_Writes, Can delete, Reaches outside, Owner only_

action=create builds a form; update edits metadata; delete removes it; replace_fields swaps the whole field list; create_link mints a PUBLIC single-use link that expires in 3 days (optionally bound to a patient, whose record the answers then overwrite); seed_defaults installs the pack's templates.

**Arguments**

| Tool | Type | Required? |
| --- | --- | --- |
| `action` | `create` \\| `update` \\| `delete` \\| `replace_fields` \\| `create_link` \\| `seed_defaults` | Required |
| `formId` | `string` | Optional |
| `patientId` | `string` | Optional |
| `name` | `string` | Optional |
| `description` | `string` | Optional |
| `isActive` | `boolean` | Optional |
| `fields` | `array` | Optional |

**Example call**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "write_form",
    "arguments": {
      "action": "create"
    }
  }
}
```

**Result**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": 200,
      "ok": true,
      "data": { "...": "the written record" }
    }
  }
}
```

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `validation_failed` | 400 | An argument is missing, of the wrong type, or outside its allowed values. |
| `not_found` | 404 | The id does not exist in your practice. A malformed id looks identical. |
| `forbidden` | 403 | The caller is not an owner of the practice. |
| `unauthorized` | 401 | The bearer token is missing, invalid or expired. |

## Common questions

### How is patient data protected?

Patient records are encrypted in transit and at rest, files are stored privately and served through short-lived signed links, and every change is written to an audit log. Staff accounts sign in with passkeys rather than shared passwords.

### Can I export my data?

Yes. Every list in HyperCRM exports to CSV from the app, and your files can be downloaded at any time. Your practice data belongs to you, and there is no export fee or waiting period — on either plan, during the trial, and after you cancel.

### How much does HyperCRM cost?

HyperCRM is paid software. Every practice starts with a 30-day free trial of the full Complete plan, with no card required. After that, plans start at €19 and €29 a month excluding VAT, banded by how many practitioners you have. Every price is printed on the pricing page rather than quoted on a call.