MCP Reference

Protocol contract, tool definitions, and security boundaries.|Endpoint: POST /api/mcp|Transport: HTTP + JSON-RPC 2.0

Overview

Semarize MCP is a JSON-RPC 2.0 server at /api/mcp. Agents authenticate via POST /api/agents/authenticate, then call MCP methods using the returned bearer token.

Current surface: draft composition and read-only inspection.

Publishing bricks and kits is not available through MCP. Publish remains a human action in the Semarize app.

Method	Behavior
`initialize`	Protocol handshake. Call first to negotiate version and capabilities.
`tools/list`	Returns tools visible to the authenticated agent.
`tools/call`	Executes a tool. Requires scope and allowlist entry.
`resources/list`	Currently returns an empty list.
`prompts/list`	Currently returns an empty list.

Authentication

Machine agents authenticate with credentials, not end-user sessions.

POST/api/agents/authenticate

Input

agent_keystringrequiredAgent key from Integration → MCP → Agents.

agent_secretstringrequiredAgent secret. Shown once at creation.

Response

access_tokenstringShort-lived bearer token for MCP requests.

expires_atstringISO 8601 expiration timestamp. Tokens last 15 minutes.

workspace_idstringWorkspace the agent belongs to.

scopesstring[]Granted scopes for this session.

Tokens are short-lived and can expire or be revoked at any time.

Clients must re-authenticate when tokens expire. There is no refresh endpoint - call /api/agents/authenticate again.

MCP endpoint

URL	`POST https://api.semarize.com/api/mcp`
Content-Type	`application/json`
Authorization	`Bearer <access_token>`
Protocol	`JSON-RPC 2.0`
Rate limit	Rate limits apply per agent. 429 responses include a `Retry-After` header.

Discovery and visibility rules

A tool appears in tools/list only when both conditions are met:

1The agent session has the required scope for that tool.

2The tool is explicitly allowlisted for that agent.

Only tools available to the current agent session are returned by tools/list. If a tool does not appear, the agent cannot call it.

Scope	Tools
`bricks:create_draft`	`bricks.create_draft`
`bricks:read`	`bricks.list`
`kits:create_draft`	`kits.create_draft`
`kits:read`	`kits.list`, `kits.get`

JSON-RPC request format

All MCP requests use JSON-RPC 2.0 envelopes.

tools/list

Request

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/list"

}

tools/call

Request

{

"jsonrpc": "2.0",

"id": 2,

"method": "tools/call",

"params": {

"name": "bricks.list",

"arguments": {

"status": "draft",

"limit": 10

}

Response envelope

Successful tool calls return content (text summary) and structuredContent (typed payload).

Response

{

"jsonrpc": "2.0",

"id": 2,

"result": {

"content": [{ "type": "text", "text": "Listed 3 brick(s)." }],

"structuredContent": { ... }

}

Tool reference

Each tool requires the listed scope and an explicit allowlist entry for the agent. All tools execute within the authenticated agent's workspace only.

TOOLbricks.create_draft

Creates a draft brick definition. Returns brick and version IDs. Does not run evaluations or publish the brick.

Scope: bricks:create_draft|Requires explicit tool allowlist.

• Draft status only - publish separately in the Semarize app
• Caller cannot set workspace_id, created_by, or status

Input

namestringrequiredBrick name. Max 120 characters.

descriptionstringoptionalShort description. Max 500 characters.

typestringrequiredOne of: boolean, score.

evaluation_promptstringrequiredEvaluation prompt stored as the brick rule. Max 10,000 characters.

Structured response

brick_idstringCreated brick ID.

brick_version_idstringCreated version ID.

TOOLbricks.list

Returns summary fields for bricks in the workspace. Read-only. Does not include rules, evaluation prompts, or full version payloads.

Scope: bricks:read|Requires explicit tool allowlist.

• No cross-workspace access
• No rule execution or export

Input

statusstringoptionalFilter: draft, published, or deprecated.

limitintegeroptional1–100. Default 20.

Response fields per brick

brick_idstringBrick ID.

brick_keystringBrick key.

brick_namestringBrick name.

statusstringdraft, published, or deprecated.

current_version_idstringCurrent version ID.

updated_atstringISO 8601 timestamp.

TOOLkits.create_draft

Creates a draft kit from existing brick IDs only. Does not create bricks, publish the kit, or allow workspace override.

Scope: kits:create_draft|Requires explicit tool allowlist.

• All brick IDs must exist in the workspace
• Brick IDs must be unique
• At least one brick required
• Transactional: creates kit, version, and brick associations atomically

Input

namestringrequiredKit name. Max 120 characters.

descriptionstringoptionalShort description. Max 500 characters.

notesstringoptionalInitial version notes. Max 500 characters.

brick_idsarrayrequiredArray of existing brick IDs.

Structured response

kit_idstringCreated kit ID.

kit_version_idstringCreated version ID.

brick_countintegerNumber of bricks included.

TOOLkits.list

Returns summary fields for kits in the workspace. Read-only. Does not include full version payloads or internal notes.

Scope: kits:read|Requires explicit tool allowlist.

• No cross-workspace access
• No mutation

Input

statusstringoptionalFilter: draft, published, or deprecated.

limitintegeroptional1–100. Default 20.

Response fields per kit

kit_idstringKit ID.

kit_codestring8-character kit code.

namestringKit name.

statusstringdraft, published, or deprecated.

current_version_idstringCurrent version ID.

updated_atstringISO 8601 timestamp.

brick_countintegerNumber of bricks in the kit.

TOOLkits.get

Returns a single kit with optional brick and readiness summaries. Read-only, no mutation, no publish capability.

Scope: kits:read|Requires explicit tool allowlist.

• Workspace-scoped lookup only
• Does not return full version payloads or brick rules

Input

kit_idstringrequiredKit ID in the authenticated workspace.

include_bricksbooleanoptionalInclude brick summary.

include_publish_readinessbooleanoptionalInclude publish-readiness summary.

Base response

kit_idstringKit ID.

kit_codestring8-character kit code.

namestringKit name.

statusstringCurrent status.

current_version_idstringCurrent version ID.

current_versionintegerVersion number.

updated_atstringISO 8601 timestamp.

included_brick_countintegerBrick count.

With `include_bricks: true`

Summary fields per included brick:

brick_idstringBrick ID.

brick_keystringBrick key.

brick_namestringBrick name.

brick_version_idstringVersion ID.

brick_versionintegerVersion number.

brick_version_statusstringVersion status.

will_promote_on_publishbooleanWhether this brick would be promoted if the kit is later published in the app.

update_availablebooleanWhether a newer published brick version is available.

With `include_publish_readiness: true`

Publish-readiness summary. This is a read-only inspection and does not enable publishing.

publishablebooleanWhether the kit can be published.

status_badgestringSummary status label (e.g. Ready, Blocked).

blockersarrayBlocking issues. Each contains: code, brick_id, brick_version_id.

warningsarrayNon-blocking issues. Each contains: code, brick_id, brick_version_id.

included_bricks_countintegerTotal bricks.

draft_bricks_to_promoteintegerDraft bricks that promote on publish.

published_bricks_includedintegerAlready-published bricks.

blockers_countintegerNumber of blockers.

warnings_countintegerNumber of warnings.

Blocker and warning objects contain only code, brick_id, and brick_version_id. No free-form messages.

Example: full inspection

tools/call request

{

"jsonrpc": "2.0", "id": 3,

"method": "tools/call",

"params": {

"name": "kits.get",

"arguments": {

"kit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"include_bricks": true,

"include_publish_readiness": true

}

Errors

JSON-RPC errors are returned inside the response body with HTTP 200. HTTP-level errors apply to auth and rate limiting.

JSON-RPC error codes

Code	Meaning	When
`-32600`	Invalid Request	Malformed JSON-RPC envelope.
`-32601`	Method not found	Unknown method or tool name.
`-32602`	Invalid params	Malformed input, missing required fields, forbidden fields, or invalid identifiers.
`-32001`	Tool forbidden	Agent lacks scope or tool allowlist entry.
`-32002`	Execution failed	Internal error during tool execution. Details are redacted.

Invalid, inaccessible, or unsupported identifiers may return -32602 Invalid params.

HTTP status codes

Status	Meaning
`200`	All JSON-RPC responses, including errors.
`401`	Missing, invalid, revoked, or expired access token.
`429`	Rate limited. Includes `Retry-After` header.
`500`	Server error.

Security and boundaries

The following boundaries apply to all MCP operations.

Workspace-bound

All operations are scoped to the agent’s workspace. No cross-workspace reads or writes.

No publish

Publishing bricks and kits is not available through MCP. Publish remains a human action in the Semarize app.

No delete or archive

MCP cannot delete, archive, or deprecate resources.

Scope + allowlist required

Tools require both the correct scope and an explicit allowlist entry for the agent.

Token required

Requests require a valid, unexpired token. Revoked or expired tokens are rejected.

MCP Reference

Overview

Authentication

Input

Response

MCP endpoint

Discovery and visibility rules

JSON-RPC request format

tools/list

tools/call

Response envelope

Tool reference

Input

Structured response

Input

Response fields per brick

Input

Structured response

Input

Response fields per kit

Input

Base response

With include_bricks: true

With include_publish_readiness: true

Example: full inspection

Errors

JSON-RPC error codes

HTTP status codes

Security and boundaries

With `include_bricks: true`

With `include_publish_readiness: true`