Connect Nuvoca to your AI assistant¶

Connect Nuvoca as an MCP server in your AI assistant. You can then create Agents, review prompts and analyze stored call summaries through natural language. You choose which permissions to grant when signing in.

This guide covers managing your Nuvoca workspace from an AI assistant. To let your voice Agent use an external MCP service during a call, follow Connect MCP tools.

Prerequisites¶

A Nuvoca account with access to the intended workspace.
An MCP client supporting Streamable HTTP, OAuth Authorization Code with PKCE S256, and Client ID Metadata Documents (CIMD) or a manually registered public OAuth application.
Permissions for the task in the intended workspace.

Connection options depend on the client, version and Nuvoca environment. A client that requires automatic dynamic registration (DCR) exclusively cannot use this access method.

1. Copy the MCP URL¶

Use this URL to connect your AI assistant to Nuvoca:

https://app.nuvoca.ai/mcp

You can also find it under Settings → API access → Connections → Connect via MCP. If you use a separate Nuvoca environment, copy the MCP URL displayed there for that environment. Managing API access requires the relevant administrator permissions.

2. Add the connection in your AI assistant¶

Open your assistant's MCP or connector settings.
Add a remote server named Nuvoca using the copied URL.
Select OAuth and start connecting. Sign in to Nuvoca in the browser that opens and complete MFA if required.
Review the client name, workspace and requested permissions. If a workspace selector appears, choose the intended workspace.
Grant only the permissions your task requires and return to the assistant.

CIMD-capable clients identify their software through metadata. If your client requires a manual Client ID, an administrator must register an OAuth application. Its callback must exactly match the client; manual registrations accept HTTPS callbacks. The client must authorize against the MCP resource.

MCP access uses OAuth. A REST API key or REST access token cannot replace it here. Agent Studio adds workflow instructions and is installed separately.

Configure the connection in a terminal¶

These commands connect your client to https://app.nuvoca.ai/mcp. Review permissions in the browser dialog that follows. For a separate Nuvoca environment, replace the URL with its MCP address.

Codex CLIClaude Code

codex mcp add nuvoca --url "https://app.nuvoca.ai/mcp"
codex mcp login nuvoca --scopes connection:verify,agents:read

The login command requests permissions for an initial read test. Authorize the required scopes again for additional tasks. Open a new chat afterwards. See the official Codex MCP guide.

claude mcp add --transport http nuvoca "https://app.nuvoca.ai/mcp"
claude mcp login nuvoca

Alternatively, open /mcp in an interactive session and sign in there. Use a version with CIMD support. See the official Claude Code MCP guide.

3. Verify the workspace and tools¶

Use verify_connection to check the connected Nuvoca workspace and granted
permissions. Then list my Agents with list_agents.
Do not change anything yet.

verify_connection requires connection:verify; list_agents requires agents:read. Verification returns the workspace name, ID and scopes. Each connection is bound to that workspace. Start another authorization to connect to a different workspace.

Choose permissions for the task¶

Task	Required scopes
Verify connection and list Agents	`connection:verify`, `agents:read`
Review prompts and Agent settings	Also `agents:configuration:read`
Create or update Agents	Also `agents:write`
Read and configure Agentic Flows	`flows:read`, `flows:write`; also `agents:read` to select Agents
Read and configure tools	`tools:read`, `tools:write`
Manage knowledge bases and documents	`knowledge-bases:read`, `knowledge-bases:write`, `documents:read`, `documents:write`
Analyze today's summaries	`call-summaries:read`; also `connection:verify` recommended
Assign existing phone numbers	`phone-numbers:read`, `phone-numbers:write`

Read and write permissions are separate. Scopes do not expand your role. Existing grants receive new scopes only through a new authorization. The references describe all MCP tools and scopes.

Review and test changes¶

Before a change, ask the assistant to read the catalog and current configuration. Review the Agent, prompt, voice and planned tool actions. You can prepare new Agents disabled and without a number; existing Agents are changed directly when you execute a write instruction.

Assigning a phone number changes routing. Saving configuration does not perform a test call. Check new configuration with a test call. Three copyable example prompts support this workflow.

Renew or revoke access¶

Access tokens last five minutes. The client can renew them using rotating refresh tokens within a grant lasting at most 24 hours. Reconnect after that period or after revocation.

Under API access → Connections → My authorizations, you can inspect and revoke your own authorizations. Administrators with the required permissions can manage their workspace's active MCP grants under Tenant MCP connections. A listed grant does not mean the client is currently online.

Troubleshoot the connection¶

Problem	Next step
MCP URL missing or OAuth unavailable	Ask your workspace administrator to check the environment.
Sign-in works but a tool is missing	Check granted scopes; authorize again for additional permissions and reload the catalog.
`FORBIDDEN` despite a visible tool	Check your current role and workspace access.
`CONFLICT` when saving	Read current configuration again and reconcile the proposal.
Creation result is uncertain	Check existing resources before creating again.
HTTP `429`	Wait for the period specified in `Retry-After`.
Client requires an API key or DCR	Check OAuth/CIMD support or manual registration.