MCP tool reference¶

The Nuvoca MCP server provides the following tools for your connected AI assistant. The client receives only tools covered by its granted scopes. Your current workspace permissions are checked on every call. Set up the connection.

Tools and scopes¶

Tool	Purpose	Scope
`verify_connection`	Get the connected workspace's name, ID and granted capabilities. This connection cannot switch workspace.	`connection:verify`
`list_agents`	List agent summaries in the connected workspace. Use zero-based page and size 1–100. Read full configuration separately.	`agents:read`
`get_agent`	Read complete editable agent configuration and revision, including the prompt. Read before updating.	`agents:configuration:read`
`create_agent`	Create an agent in the connected workspace. Supply configuration with agent and options. Returns its ID and revision. Do not blindly retry after an uncertain result; list agents first.	`agents:write`
`update_agent`	Replace an agent's editable configuration. First get_agent, modify the returned configuration and send its exact revision. On CONFLICT read again; never overwrite blindly.	`agents:write`
`get_agent_catalog`	Read allowed models, speech providers, languages, agent types and prompt variables before configuring an agent.	`agents:configuration:read`
`list_voices`	List available voices with provider and language. Filter by provider, language, gender or search; use null for unused filters. Page is zero-based; size 1–100.	`agents:configuration:read`
`get_flow_catalog`	Read allowed routing modes, models and routing prompt variables.	`flows:read`
`get_tool_catalog`	Read supported agent tool types and configuration field contracts before creating tools.	`tools:read`
`list_tool_credentials`	List safe references to existing credentials; no secrets are returned. Requires credential-read permission in addition to the tool scope.	`tools:read`
`list_tool_oauth_configurations`	List references to existing outbound OAuth configurations; no secrets. Requires credential-read permission.	`tools:read`
`list_available_mcp_tools`	List already approved outbound MCP tool references that may be assigned to an agent. Does not connect new servers.	`tools:read`
`get_pre_processing_variables`	Read supported lookup variables for pre-processing configuration.	`pre-processing:read`
`get_post_processing_variables`	Read supported variables for post-processing webhooks.	`post-processing:read`
`list_flows`	List agentic flows. Zero-based page; size 1–100.	`flows:read`
`get_flow`	Read full flow configuration and revision before updating.	`flows:read`
`create_flow`	Create an agentic flow using existing tenant agent IDs. Include a DEFAULT routing assignment.	`flows:write`
`update_flow`	Replace full flow configuration using the revision from get_flow.	`flows:write`
`delete_flow`	Permanently delete a flow using its current revision.	`flows:write`
`list_agent_tools`	List tools assigned to an agent; zero-based page and size 1–100.	`tools:read`
`get_agent_tool`	Read safe tool configuration and revision. Stored secrets are excluded.	`tools:read`
`create_agent_tool`	Create an agent tool. First read get_tool_catalog; use existing credential references where applicable.	`tools:write`
`update_agent_tool`	Replace tool configuration using its current revision. The tool type cannot change. Omitted secrets are preserved.	`tools:write`
`delete_agent_tool`	Permanently remove an agent tool using its current revision.	`tools:write`
`list_knowledge_bases`	List knowledge bases; zero-based page and size 1–100.	`knowledge-bases:read`
`get_knowledge_base`	Read a knowledge base's title and version.	`knowledge-bases:read`
`create_knowledge_base`	Create an empty knowledge base. Returns its ID for document upload and agent assignment.	`knowledge-bases:write`
`rename_knowledge_base`	Rename a knowledge base; revision is its current numeric version converted to a string.	`knowledge-bases:write`
`check_knowledge_base_deletion`	Check blocking references and obtain an assessment token before deleting a knowledge base.	`knowledge-bases:write`
`delete_knowledge_base`	Permanently delete a knowledge base and its documents using a fresh deletion assessment token.	`knowledge-bases:write`
`list_knowledge_documents`	List document metadata in a knowledge base; zero-based page and size 1–100.	`documents:read`
`get_knowledge_document`	Read document metadata. File contents are excluded.	`documents:read`
`add_knowledge_document`	Upload a UTF-8 Markdown document with at most 65536 characters into a knowledge base. Binary files use the REST upload API. No URL fetching.	`documents:write`
`delete_knowledge_document`	Permanently delete a document; revision is its current numeric version converted to a string.	`documents:write`
`list_pre_processing_profiles`	List pre-processing profiles; zero-based page and size 1–100.	`pre-processing:read`
`get_pre_processing_profile`	Read pre-processing configuration and profile version. Secrets are redacted.	`pre-processing:read`
`create_pre_processing_profile`	Create pre-processing configuration and assignments in this workspace.	`pre-processing:write`
`update_pre_processing_profile`	Replace pre-processing configuration and assignments; revision is the current profile.version as a string. Omitted secrets are preserved.	`pre-processing:write`
`delete_pre_processing_profile`	Permanently delete a pre-processing profile; revision is its current version as a string.	`pre-processing:write`
`list_post_processing_profiles`	List post-processing profiles; zero-based page and size 1–100.	`post-processing:read`
`get_post_processing_profile`	Read post-processing configuration and profile version. Secrets are redacted.	`post-processing:read`
`create_post_processing_profile`	Create post-processing configuration and assignments in this workspace.	`post-processing:write`
`update_post_processing_profile`	Replace full post-processing configuration and assignments; revision is current profile.version as a string. Omitted secrets are preserved.	`post-processing:write`
`delete_post_processing_profile`	Permanently delete a post-processing profile using its current version as a string.	`post-processing:write`
`list_phone_numbers`	List existing workspace phone numbers and their routing. Zero-based page and size 1–100.	`phone-numbers:read`
`get_phone_number`	Read a phone number's current assignment and revision.	`phone-numbers:read`
`assign_phone_number`	Assign an existing phone number to an existing agent using its current revision. Changes live routing; does not buy a number.	`phone-numbers:write`
`clear_phone_number_assignment`	Remove an existing number's default assignment using its revision. Does not release or buy the number.	`phone-numbers:write`
`list_call_summaries`	Read call summaries and from/to numbers, timestamps and duration in a bounded time range. Supply ISO timestamps with timezone, zero-based page and size 1–100.	`call-summaries:read`

Use inputs and results¶

Catalog first: Copy names, model values, voice IDs and tool fields from the relevant catalogs. list_voices supports provider, language, gender and search in addition to page and size.
Pagination: Start lists at page=0; size must be between 1 and 100. Retrieve every result page. Small configuration catalogs and individual resources are returned whole.
Create an Agent: create_agent takes configuration containing agent and options. The REST examples explain this configuration.
Update: Read the detail first, then send the edited full configuration and unchanged revision. For knowledge bases, documents and processing profiles, the revision is the current numeric version as a string. Knowledge-base deletion requires a fresh assessmentToken.
Secrets: Stored secret values are not returned. The API configuration rules explain how to preserve, remove or replace headers.
Schemas: The client can read input and output schemas through the MCP catalog. Successful calls return structured data; tool errors are marked with isError and code.

Observe the boundaries¶

add_knowledge_document uploads UTF-8 Markdown up to 65536 characters. Use the interface or REST upload for PDF, Word and other supported files. Document GETs return metadata, not source files.

Phone-number tools only change default assignments of existing numbers to individual Agents. Active Routing overrides, Flow default routes or an Agent already assigned another number can block changes. Manage Flow assignments and schedules in the interface.

These tools do not start calls or execute tool tests, webhooks or message test deliveries. Configuration changes can affect subsequent calls. Assigning a number changes routing. There is no tool to delete an individual Agent; use Agent management.

list_call_summaries returns stored summaries with call details, not transcripts. from is inclusive and to exclusive, based on when the call started. Both must be ISO timestamps with a timezone. Redacted entries contain neither summary nor phone numbers. See the daily analysis example.

Handle errors¶

Code or status	Action
`INVALID_ARGUMENT`	Check the input schema, required fields and catalog values.
`FORBIDDEN`	Check scopes, role and workspace access.
`NOT_FOUND`	Check the resource ID and connected workspace.
`CONFLICT`	Read again; resolve concurrent changes or dependencies.
`OUTPUT_TOO_LARGE`	Request a smaller page or one resource.
`UNAVAILABLE`	Check whether a change already succeeded before retrying a write.
HTTP `401`	Renew the connection or sign in again.
HTTP `429`	Wait for `Retry-After`; never blindly repeat an uncertain write.

REST and MCP share the workspace budget: initially 120 requests per minute, including at most 30 writes. Actual limits may differ. For MCP, the tool action determines whether a request counts as a write, rather than the HTTP method alone.