Malbek CLM MCP Server

Model Context Protocol server specification for Malbek Contract Lifecycle Management

Last Updated: 19 November 2026

Introduction

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.

Endpoint

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.

Authentication

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.

Client registration

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.

Scopes

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.

Token security

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.

Workspace controls

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”.

MCP features

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

Tool catalog

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:

Results and errors

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.

Rate limits

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.

Usage

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.

Resources

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.

Reference

This section documents each tool in detail. Each tool has its own page, with the same subsections:

Common to all tools:

list_search_facets

List the workspace’s searchable contract facets.

Full description

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.

Scopes

The list_search_facets tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

The tool takes no arguments. Supplying any argument is an error.

Return results

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

search_contracts

Find contracts by their searchable facets.

Full description

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.

Scopes

The search_contracts tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

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.

Return results

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

Contract summary objects

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

get_contract_details

Read one contract in full.

Full description

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.

Scopes

The get_contract_details tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

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

Return results

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_templates

List contract templates by name pattern.

Full description

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.

Scopes

The list_templates tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

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

Return results

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

get_template_details

Read one template’s forms, fields and workflow stages.

Full description

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.

Scopes

The get_template_details tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

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

Return results

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_contract

Create a contract from a template.

Full description

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.

Scopes

The create_contract tool requires contracts:full_access, and a token that names a user.

Call arguments

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

Return results

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

checkout_contract

Check a contract’s document out to the user for editing.

Full description

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.

Scopes

The checkout_contract tool requires contracts:full_access, and a token that names a user.

Call arguments

Argument Type Restrictions/limits Description
contract_unique_id string Required. 1 to 200 characters The contract’s unique id

Return results

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

checkin_contract

Check a contract’s document back in.

Full description

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.

Scopes

The checkin_contract tool requires contracts:full_access, and a token that names a user.

Call arguments

Argument Type Restrictions/limits Description
contract_unique_id string Required. 1 to 200 characters The contract’s unique id

Return results

The same attributes as checkout_contract: uniqueId, checkedOut (now false), and lockedBy and lockedOn when present.

list_contract_sections

List a contract’s document sections.

Full description

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.

Scopes

The list_contract_sections tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

Argument Type Restrictions/limits Description
contract_unique_id string Required. 1 to 200 characters The contract’s unique id

Return results

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_section_document

Get one section’s current Word document.

Full description

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 keep customXml/ and docProps/custom.xml. Never rebuild the document from text, HTML or a new blank file. A file that has lost them is flagged MISSING_CONTENT_CONTROLS on replace.

Scopes

The get_section_document tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

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

Return results

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_section_document

Replace a section’s Word document with an edited one.

Full description

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.

Scopes

The replace_section_document tool requires contracts:full_access, and a token that names a user.

Call arguments

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

Return results

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_section_markdown

Get one section as markdown.

Full description

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.

Scopes

The get_section_markdown tool requires contracts:collaborator_access or contracts:full_access.

Call arguments

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

Return results

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_section_markdown

Edit a section through its markdown, as tracked changes.

Full description

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.

Scopes

The edit_section_markdown tool requires contracts:full_access, and a token that names a user.

Call arguments

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

Edit objects

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

Return results

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

Revision history

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