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.aiThe server speaks MCP over HTTP ("Streamable HTTP"). There are two ways to connect, and both give the assistant the same tools:
| Sign in | API key | |
|---|---|---|
| For | Claude, ChatGPT and other AI apps that let you add a server by its address and sign in | Claude Code, Cursor, VS Code and other tools where you set a request header |
| The assistant works as | You: with your own role, in the tenant you choose | The key: with the key's permissions, in the key's tenant and its sub-tenants |
| Who sets it up | Any member, with their own Envocal account | An admin, who creates the key |
| You decide | Read and change or read only, and whether it may delete, when you connect | The key's permissions |
| Ended by | Disconnect under Connected apps | Revoking 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.
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 page | What it is |
|---|---|
| Organization | The 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 change | The app can create and change Agents, tools, knowledge bases, phone numbers, tenants and members, and read conversations and usage. Chosen from the start. |
| Read only | The app can read all of that and change nothing. |
| Allow this app to delete things | Off 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.
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.
| Area | Tools |
|---|---|
| Who is connected, and tenants | get_me, list_tenants, get_tenant, update_tenant, create_sub_tenant |
| Members and invitations | list_members, change_member_role, remove_member, list_invitations, invite_user, resend_invitation, withdraw_invitation |
| Agents | list_agents, get_agent, create_agent, update_agent, delete_agent, list_agent_templates, create_agent_from_template |
| An Agent's tools, knowledge and phone number | get_agent_tools, set_agent_tools, list_agent_knowledge_bases, link_knowledge_base, unlink_knowledge_base, assign_phone_number, unassign_phone_number |
| Models and voices | list_models, get_model, list_voices, get_voice |
| Tools | list_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 bases | list_knowledge_bases, create_knowledge_base, update_knowledge_base, delete_knowledge_base, list_documents, upload_document, get_document_status, delete_document |
| Phone numbers | list_phone_numbers, get_phone_number, add_phone_number, update_phone_number, delete_phone_number |
| Conversations and usage | list_conversations, get_conversation, get_usage |
| Documentation | search_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:
- 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.
- The assistant is told to show you that and to ask you.
- 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
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.