MCP Reference

Protocol contract, tool definitions, authentication, and security boundaries.|Transport: HTTP + JSON-RPC 2.0

Overview

Semarize MCP is a JSON-RPC 2.0 server for draft brick and kit authoring, inspection, and knowledge base discovery. It supports two connection methods: internal machine agents (session-based) and remote OAuth connectors (e.g. Claude).

Current surface: draft composition, update-in-place, read-only inspection, and guided publishing.

Publishing is available through MCP with readiness checks and user confirmation. KB-recommended kits require explicit confirmation before publishing without a knowledge base attached.

Method	Behavior
`initialize`	Protocol handshake. Returns server info, capabilities, and usage instructions.
`tools/list`	Returns tools visible to the authenticated principal, filtered by granted scopes.
`tools/call`	Executes a tool. Requires scope for that tool.

Connection methods

Semarize MCP supports two authentication models. Choose based on your integration.

Internal machine agents

For CLI tools, automation scripts, and server-to-server integrations.

• Authenticate via POST /api/agents/authenticate

• Session-based (15-minute tokens)

• MCP endpoint: /api/mcp

Remote OAuth connectors

For Claude, ChatGPT, and other MCP-compatible AI assistants.

• Standard OAuth 2.0 with PKCE + DCR

• User approves via Semarize consent page

• MCP endpoint: /api/mcp/oauth

Internal agent authentication

Machine agents authenticate with credentials created in the Semarize app under Integration → MCP → Agents.

POST/api/agents/authenticate

Input

agent_keystringrequiredAgent key from the MCP agents page.

agent_secretstringrequiredAgent secret. Shown once at creation.

Response

access_tokenstringShort-lived bearer token for MCP requests.

expires_atstringISO 8601 expiration. Tokens last 15 minutes.

workspace_idstringWorkspace the agent belongs to.

scopesstring[]Granted scopes for this session.

Tokens expire after 15 minutes. Re-authenticate to get a new token. There is no refresh endpoint for internal agents.

Remote OAuth authentication

Remote MCP connectors authenticate via OAuth 2.0. Semarize is the authorization server.

MCP endpoint	`POST /api/mcp/oauth`
Authorization endpoint	`/oauth/authorize`
Token endpoint	`/oauth/token`
Registration (DCR)	`POST /oauth/register`
PKCE	S256 supported
Token lifetime	Access: 1 hour. Refresh: 30 days.

The OAuth flow redirects users to the Semarize app for workspace selection and consent. Access is scoped to the selected workspace and can be revoked at any time.

Discovery metadata is available at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.

MCP endpoints

Endpoint	Auth	Use
`POST /api/mcp`	Agent session token	Internal machine agents
`POST /api/mcp/oauth`	OAuth access token	Remote connectors (Claude, etc.)

Both endpoints accept the same JSON-RPC 2.0 format and serve the same tools. Authorization header: Bearer <token>

Rate limits apply per principal. 429 responses include a Retry-After header.

JSON-RPC request format

All MCP requests use JSON-RPC 2.0 envelopes. Tool responses return curated JSON in the content array.

tools/call example

Request

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/call",

"params": {

"name": "bricks-list",

"arguments": { "status": "draft" }

}

Response

Tool results are returned as curated JSON in the content text field.

Response

{

"jsonrpc": "2.0", "id": 1,

"result": {

"content": [{ "type": "text", "text": "{...curated JSON...}" }]

}

Tool reference

All tools execute within the authenticated principal's workspace. Tool visibility is filtered by granted scopes.

Scope	Tools
`bricks:create_draft`	`bricks-create_draft`
`bricks:read`	`bricks-get_draft`, `bricks-list`
`bricks:update_draft`	`bricks-update_draft`
`kits:create_draft`	`kits-create_draft`
`kits:read`	`kits-list`, `kits-get`
`kits:update_draft`	`kits-update_draft_composition`
`kits:publish`	`kits-publish_draft`
`knowledge_bases:read`	`knowledge_bases-list`, `knowledge_bases-get`

TOOLbricks-create_draft

Creates a draft brick. Returns the full authoring-safe brick state including rule, output fields, and type-specific configuration.

Scope: bricks:create_draft

• Creates drafts only — use kits-publish_draft to publish the kit and its bricks together
• KB fields are not accepted on bricks — KB logic belongs on kits

Input

namestringrequiredBrick name. Max 120 characters.

definer_typestringrequiredOne of: boolean, score, category, string_list.

rulestringrequiredPlain English evaluation rule. Max 10,000 characters.

descriptionstringoptionalShort description. Max 500 characters.

maximum_scoreintegeroptionalRequired for score bricks only. Ignored for other types.

category_valuesstring[]optionalRequired for category bricks only. Ignored for other types.

output_fieldsobjectoptionalToggles: value, confidence, reason, evidence (all boolean).

accepted_data_typesstring[]optionalArray of: call, chat, email.

examplesarrayoptionalSnippet + outcome pairs for evaluation anchoring.

rubric_itemsarrayoptionalEvaluation guidance items.

Response

brick_idstringCreated brick ID.

namestringBrick name.

definer_typestringBrick type.

rulestringEvaluation rule.

statusstringAlways draft.

versionintegerVersion number.

app_urlstringLink to the brick in the Semarize app.

TOOLbricks-get_draft

Reads one draft brick with full authoring fields. Use this to inspect a brick before updating or to decide whether to reuse vs. create new.

Scope: bricks:read

Input

brick_idstringrequiredExisting brick ID in the workspace.

Response includes

brick_idstringBrick ID.

namestringBrick name.

definer_typestringBrick type.

rulestringEvaluation rule.

output_fieldsobjectOutput toggles.

accepted_data_typesstring[]Channel types.

examplesarrayAnchors/examples.

rubric_itemsarrayRubric guidance.

app_urlstringLink to the brick in the Semarize app.

TOOLbricks-update_draft

Updates a draft brick in place. Only send the fields you want to change \u2014 unchanged fields are preserved.

Scope: bricks:update_draft

• Only draft bricks can be updated
• Existing values are preserved for fields not included in the request

Input

brick_idstringrequiredBrick to update.

namestringoptionalUpdated name.

rulestringoptionalUpdated rule.

definer_typestringoptionalChange brick type.

descriptionstringoptionalUpdated description.

output_fieldsobjectoptionalUpdated output toggles.

accepted_data_typesstring[]optionalUpdated channels.

examplesarrayoptionalUpdated anchors.

rubric_itemsarrayoptionalUpdated rubric.

TOOLbricks-list

Lists bricks in the workspace. Returns minimal discovery fields only.

Scope: bricks:read

Input

statusstringoptionalFilter: draft, published, or deprecated.

limitintegeroptional1–100.

Response fields per brick

brick_idstringBrick ID.

namestringBrick name.

definer_typestringBrick type.

statusstringCurrent status.

TOOLkits-create_draft

Creates a draft kit from existing brick IDs. Optionally attach knowledge bases for grounded evaluation.

Scope: kits:create_draft

• All brick IDs must exist in the workspace
• At least one brick required
• KB logic belongs on kits, not bricks

Input

namestringrequiredKit name. Max 120 characters.

brick_idsstring[]requiredArray of existing brick IDs.

descriptionstringoptionalShort description.

notesstringoptionalInitial version notes.

knowledge_base_idsstring[]optionalWorkspace KB IDs to attach for grounded evaluation.

kb_modestringoptionalnone, optional_grounding, or required_grounding.

kb_reasonstringoptionalWhy the kit needs KB grounding. Setting this marks the kit as KB-recommended.

Response

kit_idstringCreated kit ID.

kit_version_idstringCreated version ID.

brick_countintegerNumber of bricks included.

app_urlstringLink to the kit in the Semarize app.

TOOLkits-update_draft_composition

Replaces the brick composition and KB configuration of a draft kit.

Scope: kits:update_draft

Input

kit_idstringrequiredKit to update.

brick_idsstring[]requiredNew ordered brick IDs.

knowledge_base_idsstring[]optionalUpdated KB attachments.

kb_modestringoptionalUpdated grounding mode.

kb_reasonstringoptionalUpdated KB reason.

TOOLkits-list

Lists kits in the workspace. Returns minimal discovery fields.

Scope: kits:read

Input

statusstringoptionalFilter: draft, published, archived, or deprecated.

limitintegeroptional1–100.

Response fields per kit

kit_idstringKit ID.

namestringKit name.

statusstringCurrent status.

brick_countintegerNumber of bricks.

TOOLkits-get

Inspects one kit with KB readiness state, warnings, blockers, and optional brick summary.

Scope: kits:read

Input

kit_idstringrequiredKit ID in the workspace.

include_bricksbooleanoptionalInclude brick summary.

include_publish_readinessbooleanoptionalInclude publish-readiness check.

Response includes

kit_idstringKit ID.

namestringKit name.

statusstringCurrent status.

kb_modestringnone, optional_grounding, or required_grounding.

kb_recommendedbooleanDerived from kb_reason.

kb_reasonstringWhy KB grounding is recommended.

kb_statusstringnot_needed, recommended_missing, required_missing, attached_not_ready, required_not_ready, or ready.

attached_kb_countintegerNumber of attached KBs.

ready_kb_countintegerNumber of ready KBs.

warningsarrayKB-derived non-blocking issues. Always present when applicable.

blockersarrayKB-derived blocking issues. Always present when applicable (e.g. required_grounding_kb_not_ready).

app_urlstringLink to the kit in the Semarize app.

TOOLkits-publish_draft

Publishes a draft kit and all its included draft bricks atomically. Three server-side enforcement layers run before publish. Always call kits-get first to check readiness.

Scope: kits:publish

• Atomic: publishes the kit and promotes all included draft bricks in one transaction
• required_grounding hard block: if kb_mode is required_grounding and no ready KB exists, publish is blocked (no bypass)
• KB recommendation gate: if kb_reason is set and no KB attached, requires explicit confirmation via confirm_without_kb
• Governance readiness: remaining brick and composition blockers are checked and enforced
• Owner/admin role required

Input

kit_idstringrequiredDraft kit ID to publish.

confirm_without_kbbooleanoptionalSet true only after user explicitly confirms publishing without a recommended KB.

Success response

publishedbooleantrue on success.

kit_idstringPublished kit ID.

kit_version_idstringPublished version ID.

versionintegerVersion number.

included_brick_countintegerTotal bricks in the kit.

promoted_draft_brick_countintegerDraft bricks promoted to published.

app_urlstringLink to review the published kit in the Semarize app.

Confirmation required response

Returned when the kit recommends a KB but none is attached:

publishedbooleanfalse.

requires_confirmationbooleantrue.

kb_recommendedbooleantrue.

kb_reasonstringWhy KB grounding is recommended.

messagestringGuidance for the user.

Blocked response

Returned when readiness blockers prevent publishing. Common blocker codes:

publishedbooleanfalse.

blockersarrayBlocking issues. Codes include: required_grounding_missing_kb, required_grounding_kb_not_ready.

warningsarrayNon-blocking issues.

attached_kb_countintegerNumber of attached KBs (for required_grounding blocks).

ready_kb_countintegerNumber of ready KBs.

TOOLknowledge_bases-list

Lists workspace knowledge bases with safe metadata only. No document bodies or chunk data.

Scope: knowledge_bases:read

Input

limitintegeroptional1–100.

Response fields per KB

kb_idstringKnowledge base ID.

public_idstringStable public identifier.

namestringKB name.

statusstringCurrent status.

ready_statestringempty, processing, partially_ready, or ready.

document_countintegerTotal documents.

ready_document_countintegerDocuments ready for retrieval.

TOOLknowledge_bases-get

Gets one knowledge base with safe metadata. No document bodies, chunks, or retrieval internals.

Scope: knowledge_bases:read

Input

knowledge_base_idstringrequiredKB ID or public ID.

Response

kb_idstringKnowledge base ID.

public_idstringStable public identifier.

namestringKB name.

statusstringCurrent status.

ready_statestringReadiness state.

document_countintegerTotal documents.

ready_document_countintegerReady documents.

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	Missing required fields, forbidden fields, or invalid values.
`-32001`	Tool forbidden	Missing required scope for this tool.
`-32002`	Execution failed	Internal error. Details are redacted.

HTTP status codes

Status	Meaning
`200`	All JSON-RPC responses, including errors.
`401`	Missing, invalid, or expired token. OAuth routes include WWW-Authenticate challenge.
`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 authenticated workspace. No cross-workspace reads or writes.

Guided publish

Three server-side layers: required_grounding blocks without a ready KB (no bypass), KB-recommended kits require explicit confirmation, and governance readiness checks catch remaining blockers. Owner/admin role required.

No delete or archive

MCP cannot delete, archive, or deprecate resources.

No runtime execution

MCP cannot process transcripts or run kits. Use the Semarize API for execution.

Scope required

Tools require the correct scope. Tools not visible to the principal do not appear in tools/list.

KB logic on kits only

Knowledge base configuration belongs on kits. Bricks reject KB fields.

Curated responses

Tool responses return authoring-safe fields only. No compiled prompts, runtime config, or retrieval internals.

Revocable access

OAuth grants and agent sessions can be revoked at any time by workspace admins.