DialNexa MCP Quickstart

This DialNexa MCP quickstart connects an MCP-compatible AI client to your workspace and verifies the connection with the read-only get_my_organization tool. Use OAuth for an interactive sign-in, or use a DialNexa API key when the client supports custom request headers.

Before you begin

Confirm that you can sign in to the DialNexa workspace you want to authorize.
Use a test workspace when evaluating tools that can change data or spend wallet balance.
Confirm that your MCP client supports remote MCP servers over Streamable HTTP.

If you plan to use an API key, see API key authentication before placing a key in local configuration or a secret manager.

Step 1: Add The DialNexa MCP Server With OAuth

Most OAuth-capable MCP hosts only need the remote server URL:

{
  "mcpServers": {
    "dialnexa": {
      "url": "https://api.dialnexa.com/v1/mcp"
    }
  }
}

Save the configuration and connect. Do not add a placeholder Authorization header when you want the client to start OAuth discovery. Your client should open the DialNexa sign-in and consent flow. Sign in if needed, review the requested read and write permissions, select the intended workspace when more than one is available, and click Allow.

DialNexa MCP OAuth consent screen showing Claude, read and write permissions, offline access, and Deny and Allow buttons.

Click Deny if the client name, permissions, or workspace is not what you expected. The MCP connection will not be authorized.

Alternative: Connect With An API Key

Most MCP hosts accept a server configuration with a URL and headers. Add the following values using your client’s settings format:

{
  "mcpServers": {
    "dialnexa": {
      "url": "https://api.dialnexa.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Configuration field names vary between clients. Keep the URL and Authorization header unchanged if your client uses a different wrapper.

Step 3: Reconnect The Client

Save the configuration, then reconnect or restart the MCP host so it initializes the new server. The client should complete MCP initialization and call tools/list automatically. Do not send workspace IDs in the server URL or tool arguments. DialNexa derives the workspace from the OAuth grant or API key.

Step 4: Verify Tool Discovery

Open the client’s tool list and confirm that it contains get_my_organization, list_agents, and list_calls. The current reference contains a dedicated page for every available tool in the MCP Tools sidebar. If no DialNexa tools appear, check the server URL, OAuth consent state or Bearer header, and client logs before attempting a tool call.

Step 5: Make A First Read-Only Call

Ask the client to identify the current DialNexa workspace. With a credential for one workspace, call get_my_organization without arguments. If the token grants several workspaces, call List My Organizations first and pass the chosen organization_id to get_my_organization and subsequent tools. The protocol request has this shape:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_my_organization",
    "arguments": {}
  }
}

Use your MCP host for normal calls. The JSON-RPC example shows what the host sends after initialization and is useful when reading logs or building a custom client.

Verify the result

A successful response contains one text content block. Parse its text value as JSON when you are building a custom client:

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"org_example\",\"name\":\"Example Workspace\"}"
    }
  ]
}

Confirm that the returned workspace name matches the workspace that owns the API key. This check prevents accidental operations in the wrong workspace.

MCP File Uploads

Use a host-provided attachment when your MCP client can pass the attached file directly. If it cannot, call Create Upload URL, upload the bytes, then call the returned finalize_tool with the upload_id. Each slot is tied to one workspace, resource, and upload kind and expires after 10 minutes.

Upload kind	Target	Finalize tool	File limit
`kb_document`	Knowledge base ID	Upload Knowledge Base Document	PDF or TXT, 100 MB
`batch_leads`	Agent ID	Create Batch Call	CSV, XLSX, or XLS, 10 MB
`workflow_leads`	Workflow ID	Add Workflow Leads	CSV, XLSX, or XLS, 10 MB

In a host that supports the upload panel, select the file in chat and wait for upload completion. A coding client that can send HTTP requests can set reveal_url: true, then PUT the file bytes with the returned headers. Allow the returned upload_host through any network restrictions. Uploading bytes alone does not create a batch, enroll leads, or add a knowledge-base document; the finalize tool performs that action. For small text or CSV content already available to the client, roughly under 50 KB, use the supported inline text field and file name. Upload Knowledge Base Text can index text directly. Send exactly one file source, and do not paste or re-encode a large attached file into tool arguments. Review the action before finalizing: a batch starts real calls, and leads added to an active workflow can immediately incur call charges. After a timeout, inspect the batch, workflow leads, or document list before retrying. A consumed or expired upload slot cannot be reused; check the result before creating a replacement.

Make your next call

Start with a list or get tool, then pass returned IDs into a state-changing tool only after reviewing its safety label and prerequisites.

Call list_agents to discover agent IDs.
Call get_agent to inspect one agent.
Review create_call before placing a billable outbound call.

Troubleshooting

Symptom	What to check
`401 Unauthorized` before OAuth starts	Confirm the client supports MCP OAuth discovery and reads the `WWW-Authenticate` header.
Consent page does not open	Reconnect the server, allow browser redirects, and confirm you can sign in to DialNexa.
Consent shows the wrong workspace	Select the intended workspace before clicking Allow. If the wrong workspace was already authorized, reconnect and authorize again.
API key returns `401 Unauthorized`	Confirm the key is active and the header starts with `Bearer` .
Server connects but tools are missing	Reconnect the client so it runs initialization and `tools/list` again.
A tool returns `isError: true`	Read the text block for the operation-specific cause and remediation.
Returned resources belong to an unexpected workspace	Stop and replace the API key with one created in the intended workspace.

See MCP responses and errors for retry decisions and confirmation rules.

Start Here

Tool Reference

Before you begin

Step 1: Add The DialNexa MCP Server With OAuth

Alternative: Connect With An API Key

Step 3: Reconnect The Client

Step 4: Verify Tool Discovery

Step 5: Make A First Read-Only Call

Verify the result

MCP File Uploads

Make your next call

Troubleshooting

​Before you begin

​Step 1: Add The DialNexa MCP Server With OAuth

​Step 2: Sign In And Review Consent

​Alternative: Connect With An API Key

​Step 3: Reconnect The Client

​Step 4: Verify Tool Discovery

​Step 5: Make A First Read-Only Call

​Verify the result

​MCP File Uploads

​Make your next call

​Troubleshooting

Before you begin

Step 1: Add The DialNexa MCP Server With OAuth

Step 2: Sign In And Review Consent

Alternative: Connect With An API Key

Step 3: Reconnect The Client

Step 4: Verify Tool Discovery

Step 5: Make A First Read-Only Call

Verify the result

MCP File Uploads

Make your next call

Troubleshooting