Skip to main content
The DialNexa MCP server lets an MCP-compatible AI client inspect and manage DialNexa resources through named tools. Connect to https://api.dialnexa.com/v1/mcp with OAuth 2.1 or a DialNexa API key, then let the client discover the available tools through the Model Context Protocol.

Who should use the DialNexa MCP server

Use the MCP server when an AI client should choose and call DialNexa operations during a conversation. Use the REST API when your application code needs deterministic request and response handling without an AI client deciding which operation to run. Both interfaces use many of the same resource IDs. MCP clients can use an interactive DialNexa sign-in or a workspace API key, while REST API integrations use API keys.

DialNexa MCP Server Endpoint And Authentication

The server implements MCP Streamable HTTP at:
OAuth 2.1 is the recommended connection method for interactive MCP clients. It uses authorization-code flow with PKCE and lets the user choose the workspace during consent. API key authentication remains available for clients that support custom request headers.

OAuth 2.1 Sign-In

Add the remote MCP URL without an Authorization header when your client supports MCP OAuth discovery. The connection follows this sequence:
  1. The client contacts the MCP endpoint and receives the protected-resource metadata location in the WWW-Authenticate header.
  2. The client discovers the DialNexa authorization server and opens a browser.
  3. Sign in to DialNexa if needed.
  4. Select every workspace this client may use. Write access is chosen per workspace and starts unticked: tick Allow writes where the client should create or change things. If no workspace has it, the client sees only the read-only tools; a write tool called for a workspace without it returns Organization <id> is connected with read-only access.
  5. Click Allow to finish, or Deny to reject the connection.
The consent screen can request these scopes: DialNexa MCP OAuth consent screen showing Claude, read and write permissions, offline access, and Deny and Allow buttons. OAuth access is limited to the workspaces and permissions approved by the user. If the credential has access to multiple workspaces, call List My Organizations, choose the intended workspace, and pass its organization_id with subsequent tool calls. This cannot grant access to a workspace outside the credential’s permissions.

API Key Authentication

Send a workspace API key as a Bearer token on every request:
The server resolves the workspace from the API key. Tool arguments cannot select a different workspace. A missing, revoked, or malformed key returns 401 Unauthorized before a tool runs. See API key authentication for key creation and storage guidance.

DialNexa MCP response privacy

External MCP results omit internal workspace and provider fields and mask credential values in configurations. Text and structured results contain the same filtered data. Webhook tools show only the host of each webhook URL, because the rest of the URL can work as a password. Inspect the returned fields instead of expecting the dashboard’s full records. Link SIP trunks in the dashboard; the external MCP catalog does not offer create_sip_trunk. Billing plans, phone number pricing, and number purchases are in the dashboard too.

DialNexa MCP tool reference

Each tool has its own reference page with the exact server description, input schema, safety level, JSON-RPC request shape, retry guidance, and related tools.

Agents

Create, inspect, configure, and remove voice agents.

Calls

Find call records and place confirmed outbound calls.

Batch Calls

Inspect campaigns, review leads, and control batch calls.

Workflows

Build workflow graphs and manage workflow execution.

Knowledge Base

Create knowledge bases, add documents or text, and manage them.

Phone Numbers

Inspect workspace phone numbers and assign them to agents. Numbers are bought in the dashboard.

Reference Data

Resolve language, voice, model, and transcriber IDs.

Templates

Find reusable agent templates and inspect their configuration.

Billing

Check wallet balance, spend limits, and billing alert emails.

Webhooks

Inspect workspace webhook configuration. Secrets and URL paths are not shown.

Organization

Identify your workspaces and create, rename, delete, or fill agent folders.

Dashboard

Read call, agent, onboarding, and weekly dashboard metrics.

Integrations

Inspect, validate, and disconnect integrations. New integrations are connected in the dashboard.

Prompt Suggestions

Read AI-generated prompt improvements for an agent.

Upload Files Through MCP

MCP supports knowledge-base text and document uploads, and batch recipient files. Use host attachments or a short-lived upload slot instead of copying large files into the conversation. See the MCP file upload workflow for supported formats, limits, and finalization steps.

Multilingual Agents And Document Processing

create_agent and update_agent accept up to three secondary_language_ids and an optional language_default_message. Choose a voice available to the connected workspace, and verify the saved draft before publishing. See the complete create-agent schema. Knowledge-base text and document uploads can return processing while indexing runs in the background. The upload response is the only status MCP shows: list_knowledge_base_documents and get_knowledge_base_document return knowledge bases, not the files inside them. Check processing in the dashboard or with the REST List Knowledge Base Documents endpoint before expecting the agent to retrieve the content. A failed document can disappear from the normal list. See document processing and recovery.

Protocol behavior

  • Transport: The server uses stateless MCP Streamable HTTP. Each request is authenticated independently with OAuth or an API key.
  • Discovery: Use the standard MCP tools/list method after client initialization.
  • Invocation: Use tools/call with the exact snake_case tool name and an arguments object.
  • Results: A successful tool returns one text content block containing the JSON-encoded result, and the same result as an object in structuredContent (a list is wrapped as { "items": [...] }, a single value as { "value": ... }).
  • Tool failures: A tool-level failure sets isError: true and returns a readable explanation in the text block.
  • IDs: Pass prefixed IDs exactly as returned, such as agent_..., call_..., batch_..., and workflow_....

Safety and confirmation

Reference pages classify every tool as read only, state changing, destructive, or billable. These tools refuse to run unless confirm: true is sent: create_batch_call, redact_call, delete_agent, delete_knowledge_base, delete_phone_number, delete_campaign, delete_organization_folder, disconnect_integration, and update_batch_call_status when the action is cancel. create_call has no confirm argument; its description tells the client to confirm the number and intent with the user first, so rely on your host’s approval prompt for it. Never add confirm: true before the user approves the exact action. After an uncertain timeout on a state-changing tool, read the affected resource before retrying. This prevents duplicate calls, purchases, or resources.

Next steps