DocumentationAPI ReferenceChangelog

Envocal API

API Reference Tools guide MCP server API Changelog

Endpoints

MCP server

Connect an AI assistant to Envocal with the Model Context Protocol, and let it build and manage Agents, tools and knowledge bases while you talk to it. Add Envocal to Claude or ChatGPT as a custom connector and sign in, or connect Claude Code, Cursor or VS Code with an API key.

The Envocal MCP server gives an AI assistant the Envocal API as tools. Connect the assistant you already use, and ask it in your own words: "Create an Agent that answers questions about orders, with a tool that looks an order up in our shop system", or "Which of our Agents had the most conversations last week?". The assistant reads the Envocal documentation, makes the calls and tells you what it did.

MCP (Model Context Protocol) is the open standard AI assistants use to reach other systems. Every tool of the server is one endpoint of the API, so the assistant can do what the API can do, no more, and only what you allow it.

Address

https://mcp.envocal.ai

The server speaks MCP over HTTP ("Streamable HTTP"). There are two ways to connect, and both give the assistant the same tools:

Sign inAPI key
ForClaude, ChatGPT and other AI apps that let you add a server by its address and sign inClaude Code, Cursor, VS Code and other tools where you set a request header
The assistant works asYou: with your own role, in the tenant you chooseThe key: with the key's permissions, in the key's tenant and its sub-tenants
Who sets it upAny member, with their own Envocal accountAn admin, who creates the key
You decideRead and change or read only, and whether it may delete, when you connectThe key's permissions
Ended byDisconnect under Connected appsRevoking the key under Vault → API keys

Connect by signing in

For Claude, ChatGPT and other AI apps that connect to a server by letting you sign in. You give the app the address, sign in to Envocal in your browser and choose what the app may do. There is no API key to create, and the app never sees your password.

Add Envocal to the app

Sign in and choose what the app may do

Your browser opens Envocal Studio. Sign in with your Envocal account if you aren't signed in already. You then get the page Connect followed by the app's name, with the address the app comes from. On it:

On the pageWhat it is
OrganizationThe tenant the app works in. A list to choose from when you are a member of several, otherwise the one you have. The app works in that tenant and its sub-tenants, as you and with your role there, and nowhere else.
Read and changeThe app can create and change Agents, tools, knowledge bases, phone numbers, tenants and members, and read conversations and usage. Chosen from the start.
Read onlyThe app can read all of that and change nothing.
Allow this app to delete thingsOff from the start. While it is off, the app can create and change but not delete. It is there when Read and change is chosen.

Click Allow. The browser goes back to the app, which is now connected. Cancel goes back to the app without connecting it. Use another account at the bottom signs you out, to sign in as someone else.

Check the connection

Ask the assistant: "Which Envocal tenant am I connected to?" It calls get_me and answers with your email, your role, the tenant and what you allowed.

The app works as you

A connected app can do what you can do in the Studio in that tenant, narrowed by what you chose on the page. An app connected by a member with the role User can't do what only an Admin can, such as managing members (see User management). What the app does is recorded as done by you, through that app.

Every app you have connected is listed in the Studio under Settings → Connected apps, where you can disconnect it: see Connected apps.

Connect with an API key

For Claude Code, Cursor, VS Code and other tools where you set a request header, and for anything that runs without a person. The server takes a tenant API key as a bearer token, the same keys as the API:

Authorization: Bearer evk_eu_...

Create an API key

In Envocal Studio, as an admin: Vault → API keys → New key (see Vault). Pick the permissions the assistant should have. The key decides what the assistant can read and change, and where: in the key's tenant and its sub-tenants.

To look around first, create a key with Read only permissions. An assistant with such a key can answer questions about your account and can change nothing.

Add the server to your assistant

Check the connection

Ask the assistant: "Which Envocal tenant am I connected to?" It calls get_me and answers with the key's name, its tenant and its permissions.

Treat the key like a password

Keep the key out of files you share or commit: use an environment variable or your assistant's own secret storage, as in the examples. If a key may have leaked, revoke it in Vault → API keys and create a new one.

What the assistant can do

Each tool is one endpoint of the Envocal API, with the same fields and the same permission. A call that the key, or what you allowed the app when you signed in, doesn't cover is refused with the missing permission named, exactly as in the API.

AreaTools
Who is connected, and tenantsget_me, list_tenants, get_tenant, update_tenant, create_sub_tenant
Members and invitationslist_members, change_member_role, remove_member, list_invitations, invite_user, resend_invitation, withdraw_invitation
Agentslist_agents, get_agent, create_agent, update_agent, delete_agent, list_agent_templates, create_agent_from_template
An Agent's tools, knowledge and phone numberget_agent_tools, set_agent_tools, list_agent_knowledge_bases, link_knowledge_base, unlink_knowledge_base, assign_phone_number, unassign_phone_number
Models and voiceslist_models, get_model, list_voices, get_voice
Toolslist_tools, get_tool, create_tool, update_tool, delete_tool, test_tool, list_tool_templates, create_tool_from_template
Vault (names only)list_credentials, list_secrets
Knowledge baseslist_knowledge_bases, create_knowledge_base, update_knowledge_base, delete_knowledge_base, list_documents, upload_document, get_document_status, delete_document
Phone numberslist_phone_numbers, get_phone_number, add_phone_number, update_phone_number, delete_phone_number
Conversations and usagelist_conversations, get_conversation, get_usage
Documentationsearch_docs, read_doc

No tool starts a call or a chat with an Agent, and no tool reads the value of a credential or a secret.

get_conversation gives a conversation as the Studio shows it when you open it: the summary, the details and the whole transcript, with every tool call the Agent made in it. For each call the assistant sees which tool, what the Agent sent, whether it worked, the error if it didn't, how long it took and the whole answer. So you can ask: "Why did the booking tool fail in yesterday's calls?" list_conversations finds the conversations, with the few details the Studio's list shows.

Deleting needs your yes

Seven tools remove something for good: delete_agent, delete_tool, delete_knowledge_base, delete_document, delete_phone_number, remove_member and withdraw_invitation. None of them deletes in one call:

  1. The first call deletes nothing. It answers with what would be deleted (for an Agent: its name, its phone number, how many tools it has, and that its widget settings go with it) and a code.
  2. The assistant is told to show you that and to ask you.
  3. Only a second call with the code deletes. The code is valid for five minutes, for that one object and for the key or the app it was given to.

An app you connected by signing in can delete only if you switched on Allow this app to delete things when you connected it. Without that, a delete tool is refused at the first call.

Your assistant also asks before it runs a tool that changes or deletes something, unless you have told it to stop asking. Leave that on for these tools.

An assistant that cannot delete

The two calls make sure nothing is deleted by accident or in passing. They can't prove that a person was asked. If an assistant must not be able to delete at all: when you sign in, leave Allow this app to delete things off, and with an API key, give the key Read only on that resource, since deleting needs Write.

Testing a tool sends a real request

test_tool sends the tool's request to the system it is for, as an Agent would in a conversation, and returns that system's answer. A tool that creates a ticket creates a ticket when it is tested.

The assistant tests each tool as it builds it, without asking you first, so it can correct the tool until the answer is right. It is told to use values that are clearly a test, to tell you what each test sent, and to ask first when a test would reach a person or cost money: a message that is sent, an order that is placed, a payment that is taken. To have it ask before every test, say so when you give it the task. A key, or an app you connected, can run 30 tests a minute.

Permissions and safety

  • With an API key, the key is the limit. The assistant can do what the key's permissions allow, in the key's tenant and its sub-tenants. Give a key only what the work needs.
  • Signed in, you are the limit. The assistant can do what you can do in the tenant you chose, narrowed to Read only if you chose that, and without deleting unless you allowed it.
  • Values in the Vault are never returned. The assistant sees the names and ids of credentials and secrets, to use them in a tool.
  • Tool calls count as API requests. They are limited per key as in the API (rate limit), and in the same way per app you have connected.

Let only an assistant you trust change tools

A tool sends a request to an address its author chooses, and carries the credential and secrets attached to it. An assistant with Write on Tools can use the credentials and secrets that your tools already use, and with Read on Vault every other one, and could make a tool that sends them to any address. An app you connect with Read and change has both.

An assistant also reads text that other people wrote: a conversation's transcript, a document, a web page. Such text can contain instructions meant for the assistant. Keep your assistant's question before changes switched on when it can change tools.

Questions

Related topics

  • API Reference
  • Tools guide
  • Your account
  • Vault

Tools guide

Create, test, share and assign Agent tools from your own systems with the Envocal API - the calls in order, the request config explained, and four complete examples you can send as they are.

API Changelog

Changes to the Envocal API, newest first. Changes that could break an integration are announced here ahead of time, with the date they take effect.

On this page

AddressConnect by signing inAdd Envocal to the appSign in and choose what the app may doCheck the connectionConnect with an API keyCreate an API keyAdd the server to your assistantCheck the connectionWhat the assistant can doDeleting needs your yesTesting a tool sends a real requestPermissions and safetyQuestions