Model Context Protocol server specification for Malbek Contract Lifecycle Management
Last Updated: 19 November 2026
Malbek provides a Model Context Protocol (MCP) server for Malbek CLM. With it, a Malbek customer can connect an MCP client of their own choosing, such as Claude, ChatGPT, Microsoft Copilot Studio or their own server-hosted agent, to their Malbek workspace. The client can then find, read, create and edit contracts on the signed-in user’s behalf.
This document is for developers who are comfortable reading detailed technical specifications and who need to know exactly:
Much of this is also described dynamically by the protocol when a client lists tools. It is collected here as a durable reference you can rely on and analyze later.
💡 Every call runs as the signed-in user. The user signs in to Malbek through the MCP client, and every tool call reaches Malbek as that user, with that user’s own roles, domains and access rules. No tool takes a user, requester or “on behalf of” argument, and the server holds no credential that can read Malbek data by itself. Two users who make the same call can therefore get different answers.
The Malbek CLM MCP server is available over Streamable HTTP, through the TLS-protected HTTPS scheme only. Each Malbek workspace has its own endpoint, on the workspace’s own host name.
| Item | Value |
|---|---|
| URL | https://{workspace}.malbekcloud.com/mcp |
| Transport | HTTPS, Streamable HTTP, JSON-RPC 2.0 (POST /mcp) |
| Session model | Stateless. The server issues no Mcp-Session-Id and
needs no session affinity; each request stands alone |
| Server name | malbek-clm |
| Server version | 1.0.0 |
| Protocol revisions | 2025-11-25 (latest), 2025-06-18,
2025-03-26 and 2024-11-05, negotiated at
initialize |
| Browser origins | A request carrying an Origin header is refused. The
server is for MCP clients, not for scripts in a web page |
{workspace} is your Malbek workspace’s host label, the
first part of the address you use to sign in to Malbek (for example
acme in acme.malbekcloud.com). A token issued
for one workspace is refused at every other workspace’s endpoint.
Malbek workspaces hold confidential commercial and legal agreements. To protect them, every MCP client must authenticate so that the Malbek user making each call is always known. A client cannot list or call tools until it has signed a user in.
The server authenticates every request with an OAuth 2.1 bearer
access token. Tokens are issued by Malbek’s authorization server through
the Authorization Code grant with mandatory PKCE (RFC 7636,
S256 only). The user signs in with their normal Malbek
sign-in (their organization’s single sign-on, or a Malbek password) and
then approves the client on Malbek’s own consent page, which lists the
access the client asked for.
| Item | Value |
|---|---|
| Flow | Authorization Code + PKCE (S256 only, required for
every client) |
| Grants supported | authorization_code, refresh_token |
| Token endpoint authentication | client_secret_post: the client sends its
client_id and client_secret in the token
request body |
| Resource discovery | RFC 9728 Protected Resource Metadata:
GET https://{workspace}.malbekcloud.com/.well-known/oauth-protected-resource/mcp |
| Authorization server (issuer) | One issuer per workspace:
https://auth.malbekcloud.com/{workspace} |
| Authorization server discovery | RFC 8414 metadata, path-inserted:
GET https://auth.malbekcloud.com/.well-known/oauth-authorization-server/{workspace} |
| Endpoints | {issuer}/oauth2/authorize,
{issuer}/oauth2/token, {issuer}/oauth2/revoke
(RFC 7009) |
resource parameter (RFC 8707) |
Optional. When sent, it must be exactly the workspace’s MCP URL,
https://{workspace}.malbekcloud.com/mcp, with no port or
trailing slash |
| Issuer identification (RFC 9207) | Every authorization response carries iss. Compare it
with the metadata issuer by exact string |
| Access token | Signed JWT (RS256, typ: at+jwt). Its
audience is the workspace’s MCP URL. Treat it as opaque |
| Not supported | Token introspection, pushed authorization requests, device
authorization, OpenID Connect discovery, the implicit and password
grants, and PKCE plain |
An unauthenticated request to /mcp receives
401 Unauthorized with
WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…",
which points a standards-following client at the discovery documents
above. The root authorization endpoints (/oauth2/authorize
without a workspace segment) answer 404 with an
explanation, so a client that drops the issuer’s path fails clearly.
Every client is registered with a workspace before its users can sign
in. A workspace administrator does this in the Malbek administrator
console (MCP clients), in two steps: they enable the
client software for the workspace, and then register the client. Malbek
knows the common MCP clients by name (ChatGPT, Claude, Copilot Studio
and others) and holds the redirect URIs each one uses, so a redirect URI
is never typed in by hand for them. A customer’s own server-hosted
agent, or a partner’s agent such as Harvey, is registered as a
custom agent with its own name and its own
https redirect URI. For a custom agent the administrator
also chooses its access (Read only, or Read and write, which is
preselected) and how it receives documents (see
get_section_document).
Registering a client gives the administrator a client_id
and a client_secret. The secret is shown once; enter both
in the MCP client’s connector settings.
Redirect URIs are compared exactly. A client secret cannot be rotated in place: to rotate, register a new client and then delete the old one.
Dynamic Client Registration (RFC 7591) is off by default. A workspace
administrator can opt in. The metadata then lists
registration_endpoint as {issuer}/register,
and a client that registers itself waits as pending
until an administrator approves it, normally when an administrator is
the first to sign in through it.
The tools a client may call are controlled by the OAuth scopes the
client holds. Malbek publishes three scopes. A client may request any of
them; the server narrows the request to what the workspace allows
instead of rejecting it, and the consent page and the token’s
scope show what was actually granted.
| Scope | Purpose | Notes |
|---|---|---|
contracts:collaborator_access |
Read access: list and read templates, search facets, contracts and contract sections | The scope for a read-only client |
contracts:full_access |
Everything contracts:collaborator_access allows, plus
creating contracts, checking contracts out and in, and replacing or
editing contract sections |
A superset of contracts:collaborator_access; it is
accepted on every read tool too |
contracts:act-as-user |
Declared for compatibility | Grants nothing extra. Calls always run as the signed-in user, whether or not a client holds it |
A scope only decides which tools a client may call.
The user’s own Malbek roles, domains and access rules decide
what each call may see or change. A client holding
contracts:full_access still cannot edit a contract its user
cannot edit in Malbek.
A workspace administrator decides which scopes each client software may have, and can narrow one registered client further. When a client’s scopes are narrowed, its refresh tokens are revoked at once, and its users sign in again to continue.
Tokens obtained through the OAuth flow are short-lived. Most users never notice the mechanisms behind them, which are documented here for completeness.
| Component | Time-to-live (TTL) | Notes |
|---|---|---|
| Authorization code | 60 seconds | Single use, bound to the PKCE challenge and the redirect URI |
| Access token | 10 minutes | Refresh it before it expires. A revoked access token stays valid until it expires, so this is the longest a revoked token can be used |
| Refresh token | 8 hours, absolute | Measured from the original sign-in. Refreshing does not extend it; after 8 hours the user signs in again |
| Section download link | 5 minutes | The download_url returned by
get_section_document. A short-lived link to one file, which
needs no token while it is valid |
A client can revoke its refresh token at
{issuer}/oauth2/revoke. A workspace administrator can
revoke a client’s access at any time by suspending or deleting it in the
administrator console. After that, the client’s refresh tokens no longer
work.
Beyond scopes, four controls decide whether a call is allowed. Each is checked on every call.
| Control | Who sets it | Effect when it denies |
|---|---|---|
| MCP access for the workspace | Malbek, on the customer’s request. Off by default | Sign-in is refused, and tool calls answer
MCP_DISABLED |
| MCP usage credit | Malbek, per the customer’s agreement | Tool calls answer CREDIT_LIMIT_EXCEEDED when the
workspace has no active credit or is well past it. Sign-in is not
blocked |
| Client software and client registration | The workspace administrator, in the administrator console | An unregistered, suspended or deleted client cannot sign users in or refresh their tokens |
| The user’s Malbek account, roles and access rules | The workspace administrator, as for any Malbek user | A deactivated user’s calls are refused. A contract the user cannot see behaves as if it does not exist |
Every tool call is recorded in the contract’s audit history as the user’s own action, marked with the client it came through, for example “via ChatGPT: Legal team”.
The server conforms to the MCP specification revisions listed under Endpoint. MCP lets a server publish several optional elements for the connecting agent. The Malbek CLM MCP server publishes tools, one resource template and server instructions. It does not publish prompts.
| Element | Provided | Description |
|---|---|---|
| Tools | Yes | Functions an agent can call. See Tool catalog |
| Tools: input schema | Yes | Every tool declares a hand-written JSON Schema (draft 2020-12).
Every object sets additionalProperties: false, so an
unknown argument is refused rather than ignored |
| Tools: output schema | No | Results are not declared with outputSchema. Every
result carries the same JSON both as structuredContent and
as a text block, and its attributes are documented in the
Reference section |
| Tools: annotations | Yes | Each tool sets title, readOnlyHint,
destructiveHint, idempotentHint and
openWorldHint. Every read tool is read-only and
idempotent |
| Resources | Yes, one template | malbek://contracts/{uniqueId}/sections/{sectionId}/versions/{version}/document:
one version of a contract section’s Word document, returned by
get_section_document. See Resources |
| Prompts | No | No pre-written prompts are published |
| Server instructions | Yes | initialize returns instructions that tell the agent the
order to call tools in, and the rules for creating and editing
contracts |
| Completions, sampling, elicitation, roots, logging | No | The server is stateless and sends no requests or notifications to the client |
This section lists every tool available to a properly authenticated
client. Not every client gets every tool: see Scopes,
and note that a Malbek deployment can switch tools off. A tool that is
switched off is absent from tools/list. In particular, the
three contract-creation tools (list_templates,
get_template_details and create_contract) are
switched off unless enabled for your deployment.
Each tool is described in more detail in the Reference section.
| Tool | Scope | Quick description |
|---|---|---|
list_search_facets |
read | List the workspace’s searchable contract facets and their data types |
search_contracts |
read | Search for contracts the user can see, by facet |
get_contract_details |
read | Read one contract in full: status, stage and every form value |
list_templates |
read | List contract templates by name pattern, with their domains |
get_template_details |
read | Read one template’s forms, fields and workflow stages |
create_contract |
full | Create a contract from a template |
checkout_contract |
full | Check a contract’s document out to the user for editing |
checkin_contract |
full | Check a contract’s document back in |
list_contract_sections |
read | List a contract’s document sections, with their versions |
get_section_document |
read | Get one section’s current Word document |
replace_section_document |
full | Replace a section’s Word document with an edited one |
get_section_markdown |
read | Get one section as markdown, for clients that cannot handle files |
edit_section_markdown |
full | Edit a section through its markdown, as tracked changes |
read: contracts:collaborator_access or
contracts:full_access. full:
contracts:full_access.
The tools are designed to be called in these sequences:
list_search_facets →
search_contracts → get_contract_details.list_templates →
get_template_details → create_contract.checkout_contract → list_contract_sections →
get_section_document → download and edit the document →
replace_section_document →
checkin_contract.checkout_contract → list_contract_sections →
get_section_markdown → edit_section_markdown →
checkin_contract.Every tool returns a standard MCP CallToolResult. On
success, isError is false and
structuredContent holds the JSON object documented for the
tool. The same JSON is repeated as a text block in content,
because some clients read only content. Some tools put an
extra text block ahead of it, a sentence the agent should act on.
On failure, the result has isError: true, a text block
of the form [CODE] detail remediation, and
structuredContent with these attributes. Failures are
returned inside the result rather than as JSON-RPC errors, so that the
agent can read them and correct its next call.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
code |
string | Always present. Enumeration, see below | What went wrong |
retryable |
boolean | Always present | Whether the same call may succeed if repeated later. Decide on this,
not on code |
detail |
string | Always present | A message that is safe to show to the user. A refusal from Malbek, such as who holds a checkout, is passed through as Malbek wrote it |
retryAfterSeconds |
int | Present with RATE_LIMITED. Positive |
How long to wait before retrying |
remediation |
string | Optional | What to do next |
expectedVersion, currentVersion |
string | Present with VERSION_CONFLICT |
The version the edit was made from, and the section’s version now |
| Code | Meaning |
|---|---|
INVALID_INPUT |
An argument is missing, malformed or refused by Malbek (for example
a form or field name the template does not have). detail
says which |
NOT_FOUND |
The contract, section, version or pending replace does not exist, or the user cannot see it. The two are deliberately indistinguishable |
FORBIDDEN_REQUESTER |
Malbek refused the call for this user, for example a domain the user has no access to |
CONFLICT |
The contract’s state refuses the call: it is checked out to someone else, not checked out, or in negotiation, or Malbek’s document checks rejected an edit |
VERSION_CONFLICT |
The section changed since the version the edit was made from. Fetch the section again and redo the edit; never resend the same edit |
INSUFFICIENT_SCOPE |
The client does not hold the scope this tool requires |
MISSING_REQUIRED_IDENTITY |
The token does not name a user. A machine credential cannot call these tools |
DELEGATION_DENIED |
The user named by the token is not active in Malbek, or the token names them incorrectly |
RATE_LIMITED |
Too many calls; see retryAfterSeconds |
UPSTREAM_ERROR |
Malbek could not complete the call. Check
retryable |
MCP_DISABLED |
MCP access is not enabled for the workspace. Retrying won’t help |
CREDIT_LIMIT_EXCEEDED |
The workspace has used its MCP credit. Retrying won’t help until credit is added |
STILL_PROCESSING |
Not an error (isError: false). Returned by
create_contract only. See that tool |
Requests that fail before a tool runs receive HTTP errors instead:
401 for a missing, expired or wrong-workspace token, an
HTTP error for a refused Origin header or host, and
JSON-RPC errors for malformed requests and unknown tools.
Each user of each client may make up to 60 tool calls per
minute in a workspace. The server also limits how many calls
run at once, and how fast it sends work to Malbek on a workspace’s
behalf. A call beyond any limit answers RATE_LIMITED with
retryAfterSeconds. The authorization server limits
/oauth2/authorize and /oauth2/token requests
per workspace and per client.
Each successful tool call and resource read consumes MCP usage credit from the workspace’s balance. Workspace administrators can read the balance and the usage per client and per tool.
The server publishes one resource template, available while
get_section_document is available.
| Item | Value |
|---|---|
| URI template | malbek://contracts/{uniqueId}/sections/{sectionId}/versions/{version}/document |
| Name | section_document |
| MIME type | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| Returned by | get_section_document, as a
resource_link |
| Scope | The same as get_section_document |
resources/read on such a URI returns the section’s Word
document at that version as a Base64 blob. Holding a URI grants nothing:
Malbek checks the user’s access again on every read. A failure is a
JSON-RPC error: -32002 when the contract, section or
version is not found, -32602 for a malformed URI, and
-32603 otherwise, with the [CODE] detail text
as the message.
This section documents each tool in detail. Each tool has its own page, with the same subsections:
Common to all tools:
contract_unique_id) is the contract’s id as shown in
Malbek, for example Contract-0407. It is a string of 1 to
200 characters. search_contracts returns it as
uniqueId.section_id) is a string
of 1 to 20 decimal digits, as list_contract_sections
returns it.version,
base_version) is an opaque concurrency token: 3 to 83
characters, of the form digits, a dot, then lowercase hexadecimal. Pass
it back unchanged. It means nothing to a person; don’t show it to
users.YYYY-MM-DD.List the workspace’s searchable contract facets.
The list_search_facets tool lists the contract facets
that search_contracts can filter on in this workspace.
Facets are configured per workspace, so call this tool before
search_contracts unless the facet names are already known.
Each facet’s name is the exact, case-sensitive string
search_contracts accepts as field, and its
dataType says which filter shape it takes. A guessed name
is rejected.
The facet list is the workspace’s configuration, not contract data, so it is the same for every user.
The list_search_facets tool requires
contracts:collaborator_access or
contracts:full_access.
The tool takes no arguments. Supplying any argument is an error.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
facets |
list[object] | Always present. Can be empty | The workspace’s searchable facets |
facets[].name |
string | Always present | The facet’s label, for example Status or
Created On. Use it exactly, spaces and case included, as
search_contracts’ field |
facets[].dataType |
string | Always present. Enumeration. One of: STRING,
DATE, NUMBER, DECIMAL,
PERCENT |
STRING takes values; the others take
from and to |
facets[].inBuilt |
boolean | Always present | true for a facet Malbek defines, false for
one the workspace configured |
Find contracts by their searchable facets.
The search_contracts tool returns summaries of the
contracts that match every filter and that the user may see. Typical
facets are Domain, Template, Status, Owner, Tags and a Created On range,
but the set is configured per workspace: call
list_search_facets for the exact names. A contract’s name
and external id are not searchable; narrow by Template,
Domain or a date range instead.
At least one filter is required; there is no unfiltered listing.
Results are summaries identified by uniqueId. Call
get_contract_details for one contract’s form values.
Results are paginated with an opaque cursor. Narrowing the filters is cheaper than paging deeply.
The search_contracts tool requires
contracts:collaborator_access or
contracts:full_access.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
filters |
list[object] | Required. 1 to 5 entries | The facets to filter on, combined with AND. Each entry is one of the two filter shapes below |
filters[].field |
string | Required. 1 to 100 characters | A facet name from list_search_facets, exactly as
spelled there (matching is case-sensitive) |
filters[].values |
list[string] | Text facets. 1 to 5 entries, each 1 to 500 characters | Values any of which may match. Each must match one of the facet’s options exactly; this is not a substring search |
filters[].from |
string | Date and numeric facets. 1 to 500 characters. Required with
to |
The inclusive lower bound. Dates are YYYY-MM-DD |
filters[].to |
string | Date and numeric facets. 1 to 500 characters. Required with
from |
The inclusive upper bound. Repeat from to match one day
or value. There is no open-ended range |
limit |
int | Optional. 20 to 100. Default 20 | The maximum number of contracts to return |
page_token |
string | Optional. 1 to 2,048 characters | The nextPageToken of a previous result, passed back
unchanged with the same filters to get the next page |
Each filter takes exactly one shape:
{"field": "Status", "values": ["Draft"]} for a text facet,
or
{"field": "Created On", "from": "2026-01-01", "to": "2026-03-31"}
for a date or numeric facet. Convert a relative period such as “the last
two months” into absolute dates.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
items |
list[object] | Always present. Can be empty | The matching contracts on this page, described in Contract summary objects |
returned |
int | Always present. 0 to limit |
The number of entries in items |
hasMore |
boolean | Always present | Whether another page is available |
nextPageToken |
string | Present only when hasMore is true |
Pass it as page_token, with the same filters, for the
next page. A token only continues the search it came from |
Each entry in items has the following attributes. An
attribute with no value is omitted.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
uniqueId |
string | Always present | The contract’s unique id. Pass it to every other contract tool |
name |
string | The contract’s name | |
status |
string | The contract’s status, for example Draft |
|
stage |
string | The contract’s current workflow stage | |
domainName |
string | The domain the contract belongs to | |
templateName |
string | The template the contract was made from | |
requesterName |
string | Who requested the contract | |
customerName |
string | The counterparty | |
createdOn, modifiedOn |
string | When the contract was created and last changed | |
version |
int | The contract’s version number | |
parentId |
int | Present for a child contract | The parent contract’s numeric id. Pass it as
get_contract_details’ contract_id |
latestSignedDocument |
boolean | Present only when true |
The contract has a signed document |
tags |
list[string] | The contract’s tags |
Read one contract in full.
The get_contract_details tool returns one contract: its
status, current stage, audit summary and every form field value.
Identify the contract by the uniqueId that
search_contracts returned, or by the
contractId that create_contract returned.
Form values come back flattened to "Form.Field" keys
(for example forms["IDs.ExternalID"]). This is
not the shape create_contract takes; use
get_template_details when composing a create.
The get_contract_details tool requires
contracts:collaborator_access or
contracts:full_access.
Supply at least one of the two arguments. Both may be supplied only if they name the same contract.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Optional. 1 to 200 characters | The contract’s unique id, for example
Contract-0407 |
contract_id |
string | Optional. 1 to 40 decimal digits | The contract’s numeric id, as create_contract or a
summary’s parentId returned it |
An attribute with no value is omitted.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
uniqueId |
string | Always present | The contract’s unique id |
id |
int | The contract’s numeric id | |
name, status, stage,
domainName, templateName,
requesterName, customerName,
modifiedOn |
string | As in Contract summary objects | |
version |
int | The contract’s version number | |
hasAmendment, hasChildContract |
boolean | Present only when true |
The contract has an amendment, or a child contract |
negotiationStatus, esignStatus |
string | Present when set | The contract’s negotiation and e-signature status |
parentId |
int | Present for a child contract | The parent contract’s numeric id |
tags |
object | The contract’s tags, as Malbek returns them | |
templateVersion, templateCanonicalId |
int | The version and canonical id of the template the contract was made from | |
auditInfo |
object | Optional. Attributes stageName (string),
totalDays (int) and notes (list[string]) |
The contract’s current stage, how many days it has been in progress, and notes |
forms |
object | Optional. Up to 200 values | Form values keyed "Form.Field". A value is a string,
number, boolean or, for a tabular form keyed by the form name, a list of
row objects (up to 100 rows). A reference to a person or record is given
as its display value. Fields with no value are omitted |
formsTruncated |
boolean | Present only when true |
Some form values were left out because the contract has more fields than one result carries |
formsNote |
string | Present with formsTruncated |
A sentence saying so |
List contract templates by name pattern.
The list_templates tool lists the contract templates
whose names match a pattern. Start here when a contract is to be created
and the template is not already known. The names it returns are the
exact strings get_template_details and
create_contract require, and the domains it reports are the
valid values for create_contract’s
domain_name.
A pattern is mandatory. Use * to list every template,
which may be long.
💡 This tool is switched off unless contract creation is enabled for your deployment.
The list_templates tool requires
contracts:collaborator_access or
contracts:full_access.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
template_name_pattern |
string | Required. 1 to 200 characters | A name pattern with * as the wildcard, for example
NDA* or *Services* |
offset |
int | Optional. 0 or more. Default 0 | The number of templates to skip |
limit |
int | Optional. 1 to 100. Default 50 | The maximum number of templates to return |
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
items |
list[object] | Always present. Can be empty | The matching templates |
items[].name |
string | The template’s exact name | |
items[].label |
string | The template’s display label | |
items[].canonicalId |
int | The template’s canonical id. Distinguishes templates that share a name | |
items[].state |
string | The template’s state | |
items[].domains |
list[string] | The domains the template can be used in | |
offset |
int | Always present | The offset this page starts at |
returned |
int | Always present | The number of entries in items |
totalMatched |
int | Always present | The number of templates matching the pattern, across all pages |
hasMore |
boolean | Always present | Whether more templates are available |
nextOffset |
int | Present only when hasMore is true |
The offset for the next page |
Read one template’s forms, fields and workflow stages.
The get_template_details tool returns one template’s
forms, their fields, and the template’s workflow stages. Call it before
create_contract: it is the only source of the exact form
and field names that create_contract’s forms
must use.
A template with many forms is large, so pass form_names
to limit the answer to the forms needed. Deprecated and hidden fields
are left out, because they must not be filled in. Fields come in the
order the template defines.
💡 This tool is switched off unless contract creation is enabled for your deployment.
The get_template_details tool requires
contracts:collaborator_access or
contracts:full_access.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
template_name |
string | Required. 1 to 200 characters | The exact template name, as list_templates returned it.
Not a pattern |
canonical_id |
int | Optional. 0 or more | The template’s canonical id from list_templates, to
choose between templates that share a name |
version |
int | Optional. 0 or more | A specific template version. Omit for the current one |
include_sections |
boolean | Optional. Default false |
When true, each field reports the section it belongs
to |
form_names |
list[string] | Optional. 1 to 50 unique entries, each 1 to 200 characters | Return only these forms. Names are case-sensitive |
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
name, label, state |
string | The template’s name, display label and state | |
canonicalId |
int | The template’s canonical id | |
version |
int | Present when requested | The version argument, echoed |
stages |
list[object] | Optional. Attributes name, label and
stageType (strings) |
The template’s workflow stages |
forms |
list[object] | Optional. Up to 100 forms | The template’s forms |
forms[].name |
string | Always present | The form’s exact name: a key of create_contract’s
forms |
forms[].label, forms[].type |
string | The form’s display label and type. A tabular form takes rows | |
forms[].fields |
list[object] | Optional. Up to 300 fields across all forms | The form’s fields |
forms[].fields[].name |
string | Always present | The field’s exact name: a key inside the form in
create_contract’s forms |
forms[].fields[].label, type,
usage |
string | The field’s display label, data type and usage | |
forms[].fields[].defaultValue |
any | The field’s default value | |
forms[].fields[].sensitive |
boolean | Present only when true |
The workspace marked this field sensitive |
forms[].fields[].section |
string | Present with include_sections |
The section the field belongs to |
unknownForms |
list[string] | Present when form_names named forms the template
doesn’t have |
Those names. unknownFormsNote explains |
truncated |
boolean | Present only when true |
The template has more forms or fields than one result carries.
truncatedNote explains; use form_names |
Create a contract from a template.
The create_contract tool creates one contract from a
template and returns its id. Call get_template_details
first: forms must use that template’s exact form and field
names, and a mistake is rejected, not corrected.
The contract is attributed to the signed-in user. There is no requester argument, and supplying one is an error.
Creating a contract can take Malbek a while. The tool waits up to 75
seconds and reports CREATED,
CREATED_WITH_WARNINGS or STILL_PROCESSING.
There is no idempotency key, so never repeat a create
that returned STILL_PROCESSING: the contract was probably
made. To find it, call search_contracts with a Template
filter and a Created On range covering today, then compare each
candidate’s forms["IDs.ExternalID"] in
get_contract_details with the external_id you
sent. Sending an external_id is strongly recommended for
this reason.
💡 This tool is switched off unless contract creation is enabled for your deployment.
The create_contract tool requires
contracts:full_access, and a token that names a user.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
template_name |
string | Required. 1 to 200 characters | The exact template name, as list_templates returned
it |
domain_name |
string | Required. 1 to 200 characters | The domain the contract belongs to, from
list_templates’ domains. The user must have
access to it |
forms |
object | Required. 1 to 100 forms, each with up to 300 fields | Form values keyed by form name, then field name:
{"AgreementHeader": {"AgreementName": "NDA - Acme"}}. A
value is a string (up to 10,000 characters), number, boolean or
null. A tabular form takes rows keyed by row number as a
string:
{"Esignature": {"0": {"Role": "Signer", "Email": "a@b.com"}}} |
state |
string | Optional. 1 to 100 characters | The contract’s initial state. Omit it to use the template’s default |
external_id |
string | Optional. 1 to 200 characters | Your own identifier for the contract. Strongly recommended; see above |
sections |
object | Optional. Exactly 1 section, with 1 to 500 paragraphs of up to 20,000 characters each | Section text: one section name mapped to its paragraphs, in order |
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
status |
string | Always present. Enumeration. One of: CREATED,
CREATED_WITH_WARNINGS, STILL_PROCESSING |
The outcome. None of them is an error |
requestId |
int | Always present | Malbek’s id for the create request. Quote it to Malbek support |
contractId |
int | Optional. Absent with STILL_PROCESSING, or if the id is
not available yet |
The new contract’s numeric id. Pass it as
get_contract_details’ contract_id |
warnings |
list[string] | Present with CREATED_WITH_WARNINGS |
What Malbek could not set |
elapsedMs |
int | Always present. Non-negative | How long the create took, in milliseconds |
note |
string | Present when contractId is absent |
What to do next to find the contract |
Check a contract’s document out to the user for editing.
The checkout_contract tool checks a contract’s document
out to the signed-in user, as Malbek’s Checkout does:
other users see it as checked out and cannot edit it until it is checked
in. A section can be replaced or edited only while the contract is
checked out to the user.
Checking out a contract the user already has checked out succeeds and
changes nothing. If someone else has it, the CONFLICT error
names them.
The checkout_contract tool requires
contracts:full_access, and a token that names a user.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Required. 1 to 200 characters | The contract’s unique id |
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
uniqueId |
string | Always present | The contract’s unique id |
checkedOut |
boolean | Always present | Whether the contract is now checked out |
lockedBy |
string | Optional | Who holds the checkout |
lockedOn |
string | Optional | When it was checked out |
Check a contract’s document back in.
The checkin_contract tool checks a contract’s document
back in, releasing the checkout so others can edit it. Call it only once
the user’s editing is finished.
Only the user who checked the contract out, or a user who manages contracts in its domain, may check it in. An agent should not check in someone else’s contract unless the user explicitly asks. The error names the holder.
The checkin_contract tool requires
contracts:full_access, and a token that names a user.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Required. 1 to 200 characters | The contract’s unique id |
The same attributes as checkout_contract:
uniqueId, checkedOut (now false),
and lockedBy and lockedOn when present.
List a contract’s document sections.
The list_contract_sections tool lists one contract’s
document sections, each with its sectionId, file name,
size, type and version. Call it before
get_section_document, get_section_markdown,
replace_section_document or
edit_section_markdown: sectionId names the
section to them, and version is what the edit tools’
base_version must be.
Every replace or edit makes a new contract version and changes the version of every section, so list the sections again after one.
The list_contract_sections tool requires
contracts:collaborator_access or
contracts:full_access.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Required. 1 to 200 characters | The contract’s unique id |
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
uniqueId |
string | Always present | The contract’s unique id |
checkedOutBy |
string | null when the contract is not checked out |
Who holds the contract’s checkout |
sections |
list[object] | Always present. Can be empty | The contract’s sections, described below |
sections[].sectionId |
string | Always present. Decimal digits | The section’s id |
sections[].name, sections[].label |
string | The section’s name and display label | |
sections[].category |
string | Enumeration, for example SECTION or
AMENDMENT_SECTION |
The kind of section. Only SECTION and
AMENDMENT_SECTION sections stored as Word documents can be
replaced |
sections[].fileName |
string | The stored file’s name | |
sections[].contentType |
string | A MIME type | The stored file’s type |
sections[].size |
int | Non-negative | The stored file’s size in bytes |
sections[].version |
string | Always present. An opaque version token | The section’s current version |
sections[].modifiedOn,
sections[].modifiedBy |
string | When the section was last changed, and by whom |
Get one section’s current Word document.
The get_section_document tool returns one section’s
current Word document (DOCX), with its file name, size and version.
To read or edit the file, download download_url when the
result has one: a short-lived https link that expires
within five minutes. Call the tool again for a fresh link rather than
reusing an old one. The result also carries a resource_link
to the section-document resource (see Resources), which
a client can read with resources/read. When no link can be
given, download_unavailable says why.
For a custom agent, the workspace administrator chooses how the document is handed over, to match what the agent supports:
| Delivery | What the result carries |
|---|---|
| Download link (default) | download_url and the resource_link |
| MCP resource | the resource_link only (no download_url),
to read with resources/read |
| Embedded | the DOCX as an embedded Base64 blob, up to a size the administrator
sets (at most 25 MB), and no download_url. A larger file
gets download_unavailable |
A download_url points at the workspace’s document
storage host, for example
<bucket>.s3.us-east-1.amazonaws.com. An agent whose
network only reaches listed hosts must allow it; the administrator
console shows the workspace’s host beside the Download link option.
To edit the section: check the contract out with
checkout_contract, edit the downloaded document, then call
replace_section_document with base_version set
to the version returned here.
💡 Keep the document’s content controls. The DOCX carries content controls (
<w:sdt>elements) and custom XML parts that Malbek uses to identify the document and its sections. Edit the downloaded file in place: never delete, add, move, merge or split a content control, never change its properties, and keepcustomXml/anddocProps/custom.xml. Never rebuild the document from text, HTML or a new blank file. A file that has lost them is flaggedMISSING_CONTENT_CONTROLSon replace.
The get_section_document tool requires
contracts:collaborator_access or
contracts:full_access.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Required. 1 to 200 characters | The contract’s unique id |
section_id |
string | Required. 1 to 20 decimal digits | The section’s id, from list_contract_sections |
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
sectionId |
string | Always present | The section’s id |
version |
string | Always present. An opaque version token | The version of the document returned. Pass it as
base_version when replacing |
fileName |
string | Always present | The document’s file name |
size |
int | Optional. Non-negative | The document’s size in bytes |
mimeType |
string | Always present | The document’s MIME type, normally the DOCX type |
uri |
string | Always present | The section-document resource URI for this version |
download_url |
string | Optional. https |
A short-lived link to the document. A bearer credential until it expires: do not log or share it |
download_expires_at |
string | Present with download_url |
When the link expires |
download_unavailable |
string | Present when there is no link | Why the file can’t be handed out, and what to do instead |
content also carries a resource_link to
uri. Where a deployment allows it, a small document may be
embedded in content as a Base64 blob instead of a link.
Replace a section’s Word document with an edited one.
The replace_section_document tool replaces one section’s
DOCX with an edited one, creating a new contract version. The previous
version stays in the contract’s history.
The contract must be checked out to the user
(checkout_contract), and base_version must be
the version list_contract_sections or
get_section_document just returned. If the section changed
since, the call fails with VERSION_CONFLICT, and the
document must be fetched and edited again, never resent.
The edited file is sent as file, an uploaded-file object
that the server downloads from download_url. Only Word
documents (DOCX) are accepted, up to 25 MB, and only from file hosts the
deployment allows (today, the hosts ChatGPT stores uploads on). The
tool’s _meta declares
{"openai/fileParams": ["file"]}. A client that cannot
upload files should use edit_section_markdown instead.
Malbek checks the document before it replaces the section. If the
checks flag the file, nothing is replaced yet: the result is
needs_confirmation, with a pendingId and the
issues. Show them to the user, then call the tool again with
pending_id and accept: true to replace anyway,
or accept: false to discard. If the issues include
MISSING_CONTENT_CONTROLS, do not accept: discard, fetch the
section again and redo the edit on that copy.
The replace_section_document tool requires
contracts:full_access, and a token that names a user.
Supply contract_unique_id, section_id and
base_version, and then exactly one of: file,
or pending_id with accept.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Required. 1 to 200 characters | The contract’s unique id. The contract must be checked out to the user |
section_id |
string | Required. 1 to 20 decimal digits | The section’s id |
base_version |
string | Required. An opaque version token | The version the edit was made from. On a confirmation call, the same
base_version as the call that returned the
pendingId |
file |
object | Required unless pending_id is sent |
The edited DOCX: download_url (string, required),
file_id (string, required), mime_type and
file_name (strings, optional; neither is trusted or
used) |
pending_id |
string | Required with accept, instead of file.
UUID format |
The pendingId a needs_confirmation result
returned |
accept |
boolean | Required with pending_id |
true replaces the section with the flagged file anyway;
false discards it |
comment |
string | Optional. Up to 1,000 characters | A note for the new contract version’s history |
Provided the call concludes without error, the result’s
status says what happened. A sentence telling the agent
what to do next precedes the JSON in content.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
status |
string | Always present. Enumeration. One of: replaced,
needs_confirmation, discarded |
The outcome |
sectionId |
string | Always present | The section’s id |
previousVersion |
string | With replaced |
The version that was replaced |
version |
string | With replaced |
The section’s new version. Every section of the contract has a new version now |
fileName |
string | With replaced |
The section’s file name, which is kept from the original |
baseVersion |
string | With needs_confirmation |
The version the pending replace was checked against |
pendingId |
string | With needs_confirmation. UUID format |
Pass it as pending_id to accept or discard the
replace |
validationErrors |
list[string] | With needs_confirmation |
The issues Malbek’s checks found, for example
MISSING_CONTENT_CONTROLS |
Get one section as markdown.
The get_section_markdown tool returns one section’s
current Word document as markdown, for clients that cannot download or
upload DOCX files. A client that can should use
get_section_document and
replace_section_document.
Each block (a paragraph, or a whole table) sits between
<!-- bid:N start --> and
<!-- bid:N end --> markers. Inside a table,
<!-- c:R.C --> marks each cell by row and column.
Headings carry no block id and cannot be edited this way. The markdown
is returned as its own text block in content, unescaped, so
that it can be quoted verbatim.
The result’s version is what the block ids are valid
for: pass it unchanged as edit_section_markdown’s
base_version, never invent a block id, and call this tool
again after any change to the section.
The get_section_markdown tool requires
contracts:collaborator_access or
contracts:full_access.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Required. 1 to 200 characters | The contract’s unique id |
section_id |
string | Required. 1 to 20 decimal digits | The section’s id, from list_contract_sections |
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
sectionId |
string | Always present | The section’s id |
version |
string | Always present. An opaque version token | The version the block ids are valid for |
The markdown itself is the text block in content. Only
bold and italic formatting is represented.
Edit a section through its markdown, as tracked changes.
The edit_section_markdown tool edits one section through
the markdown get_section_markdown returned. It creates a
new contract version in which every change is a tracked change by the
user, with the edit’s comment beside it, for a reviewer to accept or
reject in Word or in Malbek.
The contract must be checked out to the user
(checkout_contract), and base_version must be
the version get_section_markdown returned. If the section
changed since, the call fails with VERSION_CONFLICT: call
get_section_markdown again and redo the edits on the new
block ids.
Each edit names a block by its id (bid), and its
expect is the block’s first few words copied verbatim, so
an edit aimed at the wrong block is refused rather than applied. To
change words inside a block, use op: replace with
find (copied verbatim from that block) and
text; add occurrence when find
occurs more than once in the block. Without find,
replace rewrites the whole block. delete
removes find, or the whole block without it.
insert_before and insert_after add a new
paragraph styled like the block. To edit a table cell, give the table’s
bid and the cell’s R.C; a whole table cannot
be replaced or deleted. Several non-overlapping find edits
may target one block, but a whole-block change must be the only edit on
its block.
Edits are applied together or not at all. If any edit cannot be
applied, the result is INVALID_INPUT naming each failed
edit, and nothing changed. If Malbek’s document checks reject the edited
document, the result is CONFLICT naming the issues, and
nothing changed; sending the same edits again will fail the same
way.
The edit_section_markdown tool requires
contracts:full_access, and a token that names a user.
| Argument | Type | Restrictions/limits | Description |
|---|---|---|---|
contract_unique_id |
string | Required. 1 to 200 characters | The contract’s unique id. The contract must be checked out to the user |
section_id |
string | Required. 1 to 20 decimal digits | The section’s id |
base_version |
string | Required. An opaque version token | The version get_section_markdown returned
with the markdown the edits were made from |
edits |
list[object] | Required. 1 to 100 entries | The changes, described in Edit objects |
comment |
string | Optional. Up to 1,000 characters | A note for the new contract version’s history |
Each entry in edits has the following attributes.
bid, op and expect are required
in every edit.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
bid |
int | Required. 1 or more | The block: N in <!-- bid:N start -->
of the markdown as fetched. Earlier edits in the same call do not
renumber blocks |
op |
string | Required. Enumeration. One of: replace,
delete, insert_before,
insert_after |
What to do |
expect |
string | Required. 1 to 500 characters | The first few words (3 to 8) of the block, or of the cell with
cell, copied verbatim |
cell |
string | Optional. R.C, each part 1 to 6 digits, for example
2.3 |
For a table: the cell to edit, from its
<!-- c:R.C --> marker |
find |
string | Optional. 1 to 500 characters | For replace and delete: the text inside
the block or cell to change, copied verbatim. Omit to change the whole
block or cell |
occurrence |
int | Optional. 1 to 1,000 | With find: which match in the block to change, counting
from 1 |
text |
string | Required except for delete. Up to 10,000
characters |
The new text, in the same markdown (**bold**,
*italic*). An empty string with find removes
just that text |
comment |
string | Optional. Up to 1,000 characters | Why the change was made, in a short sentence. The reviewer sees it as a Word comment on the change. Give one on every edit |
Provided the edits are applied, the result has the following
attributes. A sentence telling the agent what to do next precedes the
JSON in content.
| Attribute | Type | Restrictions/limits | Description |
|---|---|---|---|
status |
string | Always present. Always replaced |
The edits were stored as tracked changes |
sectionId |
string | Always present | The section’s id |
previousVersion |
string | Always present | The version the edits were applied to |
version |
string | Always present | The section’s new version. The old block ids no longer apply |
fileName |
string | Always present | The section’s file name |
| Date | Changes |
|---|---|
| 2026-11-19 | Custom agents: the administrator chooses access and document delivery at registration |
| 2026-11-16 | get_section_document: per-agent document delivery
(download link, MCP resource, embedded) |
| 2026-11-14 | First edition, for server version 1.0.0: thirteen tools, the section-document resource, and section editing through markdown |