MCP tools
Public MCP tool surface, OAuth, and governed execution for agent clients.
Overview
Numezis exposes a remote MCP server for Claude, ChatGPT, and other MCP clients.
tools/list publishes callable domain façades. A façade runs one governed API
operation: reads stay reads, and mutations still follow module activation,
permissions, and approval policy.
End-user setup (connectors, OAuth screenshots) lives in the MCP product guide. This page documents the integration contract for builders.
Endpoint and transport
| Item | Value |
|---|---|
| URL | https://www.numezis.com/mcp |
| Transport | Streamable HTTP (JSON-RPC 2.0) |
| Auth | OAuth 2.0 with Dynamic Client Registration |
Send portal context through the authenticated session established at OAuth time.
Tool execution uses the same AccessMode rules as the company portal (/c).
Tool discovery
After authorization, call tools/list. The list is paginated (nextCursor).
Each entry is one callable façade, named numezis.<domain>.<verb> or
numezis.<domain>.<family>.<verb>. The list does not include
numezis.load_domains, a retired alias, or a generic dispatcher such as
sales.query. A second call returns the same names.
Each tool includes:
name— the façade to pass totools/calldescription— the consent sentence shown before the host asks the userinputSchema— JSON Schema; a family façade takesresourceplusargsannotations.title— localized title (Domain · Family · Verb)annotations.readOnlyHintandannotations.destructiveHint— whether the call only reads, or can change records
Only façades for enabled modules and effective permissions appear for
the connected user. _meta.toolAdmission is domain_facade_catalog.
Execution and approvals
- Client sends
tools/callwith tool name and validated arguments. - Server runs policy checks (module, permission, company status).
- Critical tools may return an approval token instead of applying the mutation.
- User confirms in Numezis UI; client retries with the approval reference.
Do not bypass approval steps in automation—use non-critical read tools to preflight data, then surface approval UX to the user.
Errors
MCP errors mirror API semantics: authorization failures, validation errors, and rate limits are returned as structured RPC errors. Log correlation ids from responses when opening support tickets.