# MCP server (https://docs.envocal.ai/api-reference/mcp/) > 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](/api-reference) 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 ```text 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 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](/api-reference#permissions) | | Ended by | **Disconnect** under [Connected apps](/account#connected-apps) | Revoking the key under [Vault → API keys](/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. ### 1. Add Envocal to the app **Claude** In Claude on the web or in the desktop app, Envocal is added as a **custom connector**: 1. Open **Customize → Connectors**, or **Settings → Customize → Connectors**. Both lead to the same place. 2. Click **Add** and choose to add a custom connector. 3. Give it a name, such as `Envocal`, and enter the address `https://mcp.envocal.ai`. 4. Keep the sign-in settings Claude suggests, and leave the OAuth client ID and secret empty: Claude identifies itself to Envocal on its own. Click **Add**. 5. Click **Connect** on the new connector. Your browser opens Envocal for the next step. To use it in a conversation, switch the connector on in the chat's menu of connectors and tools. On a Team or Enterprise plan, an owner adds the connector once for everyone, under **Organization settings → Connectors**. Each member then clicks **Connect** and signs in with their own Envocal account, so Claude works with that member's own access. Claude's menus change now and then. Its own guide has the current names: [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). **ChatGPT** In ChatGPT, Envocal is added as a **custom MCP server**: 1. Go to where ChatGPT lets you add one. OpenAI's guide shows the way and the current names: [Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt). 2. Give it a name, such as `Envocal`, and a short description. 3. Enter the address `https://mcp.envocal.ai`, exactly so, with nothing after it. 4. For authentication, choose OAuth, the choice where you sign in. Leave a client ID and secret empty if they are asked for: ChatGPT identifies itself to Envocal on its own. 5. Create it. ChatGPT sends your browser to Envocal for the next step, then or the first time you use it. Whether you can add a custom MCP server depends on your ChatGPT plan and, in a workspace, on what its admin allows. **Another app** Give the app this, wherever it lets you add a remote MCP server: | Setting | Value | | --- | --- | | Address | `https://mcp.envocal.ai` | | Transport | HTTP (Streamable HTTP) | | Sign-in | OAuth. The app finds where to sign in from the address. There is no client ID or secret to enter | An app can sign in if it identifies itself by a web address of its own (a client ID metadata document, the way the MCP specification recommends). Envocal has no registration step for apps (no dynamic client registration). An app that needs one can't sign in. If it lets you set a request header, connect it [with an API key](#connect-your-assistant) instead. ### 2. 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. ### 3. 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](/admin/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](/account#connected-apps). **The page says: This is not an app we know** Any app may ask to connect. Claude and ChatGPT are shown by their names. For any other app the page is headed **Connect an app** and shows the address the app really comes from, with the name it gives itself after it. A name is only what an app says about itself, so go by the address: click **Allow** only if you trust that address with your account, and **Cancel** if you didn't expect the page at all. **The page says: This app runs on your computer** Some apps are programs on your own computer, not websites, and the browser hands the result back to the program. Any program on your computer could ask in such an app's name. Go on only if you started connecting the app yourself, just now. **How do I change the tenant or what the app may do?** Connect the app again from the app and choose differently on the page. Connecting the same app to the same tenant again takes the place of the earlier connection. If you chose another tenant, the earlier connection stays under [Connected apps](/account#connected-apps) until you disconnect it there. **When does a connection end?** - You click **Disconnect** under [Connected apps](/account#connected-apps): the app loses its access at once. - You change your password: every app you have connected is disconnected. - The app isn't used for 30 days. - You are no longer a member of the tenant: the app can no longer reach it. To use the app again, connect it again from the app. Removing the connector in the app itself doesn't always end its access to Envocal: disconnect it in the Studio to be sure. ## 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: ```text Authorization: Bearer evk_eu_... ``` ### 1. Create an API key In Envocal Studio, as an admin: **Vault → API keys → New key** (see [Vault](/vault#api-keys)). Pick the [permissions](/api-reference#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. ### 2. Add the server to your assistant **Claude Code** Run this in a terminal, with your own key: ```bash claude mcp add --transport http envocal https://mcp.envocal.ai \ --header "Authorization: Bearer evk_eu_..." ``` To share the server with everyone who works in a project without sharing a key, put it in the project's `.mcp.json` and keep the key in an environment variable: ```json { "mcpServers": { "envocal": { "type": "http", "url": "https://mcp.envocal.ai", "headers": { "Authorization": "Bearer ${ENVOCAL_API_KEY}" } } } } ``` **Cursor** Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` to have it everywhere. Keep the key in an environment variable: ```json { "mcpServers": { "envocal": { "url": "https://mcp.envocal.ai", "headers": { "Authorization": "Bearer ${env:ENVOCAL_API_KEY}" } } } } ``` **VS Code** Add the server to `.vscode/mcp.json` in your workspace, or run **MCP: Open User Configuration** to have it everywhere. VS Code asks for the key the first time the server starts and stores it for you, so the key is not in the file: ```json { "inputs": [ { "type": "promptString", "id": "envocal-api-key", "description": "Envocal API key", "password": true } ], "servers": { "envocal": { "type": "http", "url": "https://mcp.envocal.ai", "headers": { "Authorization": "Bearer ${input:envocal-api-key}" } } } } ``` **Another assistant** Any MCP client that connects to a remote server over HTTP and lets you set a header works. Give it: | Setting | Value | | --- | --- | | Address | `https://mcp.envocal.ai` | | Transport | HTTP (Streamable HTTP) | | Header | `Authorization: Bearer evk_eu_...` | ### 3. 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](/api-reference), with the same fields and the same [permission](/api-reference#permissions). 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. **Which tenant does a tool work in?** The key's own, or the tenant you chose when you signed in. Every tool also takes a `tenantId`: the assistant gives it to work in a sub-tenant, for example a customer's. `list_tenants` shows the tenants it reaches. A tenant outside that reach is refused. **How do the tools differ from the API's endpoints?** In five places, to suit an assistant: - **`update_agent` and `update_tool` take only what should change.** The endpoints replace the whole Agent or tool; the MCP tools read it first, put the changes on top and save it, so an assistant that changes an Agent's instructions can't wipe its other settings by leaving them out. - **A list is answered 25 items at a time, with long values shortened.** A list tool such as `list_agents` takes `search` (only the items in which a text occurs, such as an Agent's name), `limit` (up to 200), `offset` (to read on) and `full` (nothing shortened). The answer says how many there are in all. The tool that reads one object, such as `get_agent`, always gives all of it. `list_conversations` is paged by the API itself, with `page` and `pageSize`. - **`upload_document` takes the document as text**, or as base64 for a file that isn't text, such as a PDF. One document per call, at most 20 MB. - **Deleting takes two calls**: see [Deleting needs your yes](#deleting-needs-your-yes). - **`search_docs` and `read_doc`** read this documentation, so the assistant can look up how something works before it does it. They are not part of the API. **What does the assistant see when a call is refused?** The API's own answer: the status and the message, which says what is wrong and how to write it. The assistant corrects the call and tries again. Nothing is saved by a refused call. ## 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](/api-reference#rate-limits)), 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 **Is my API key shown to the AI model?** No. Your assistant's program sends the key to Envocal as an HTTP header. It is not part of the conversation, and no tool returns it. **When do I use the MCP server and when the OpenAPI spec?** Use the MCP server when an assistant should do the work in your account now: set up an Agent, change a tool, look something up. Use the [OpenAPI spec](https://docs.envocal.ai/openapi.json) when you, or a coding agent, write a program that calls the API later, such as a provisioning job or a billing report. **Can I have several assistants connected?** Yes. Signed in, each app is its own connection under [Connected apps](/account#connected-apps), and you can disconnect one without affecting the others. With API keys, create a key for each, so you can give each its own permissions and revoke one alone. **Does the AI app get my Envocal password?** No. You sign in on Envocal's own page in your browser. The app gets a connection that works only at the MCP server, for the tenant and with the permissions you chose, and that you can end under [Connected apps](/account#connected-apps). **The assistant says the server can't be reached, or it is refused** - **401** with an API key: the key is missing, mistyped, revoked or expired. Check that the header is `Authorization: Bearer ` followed by the whole key. - **The app asks you to connect or sign in again**: its connection has ended (see [When does a connection end?](#connection-ends)). Connect it again from the app. - **403** on a tool: the permission named in the message is missing. For a key, add it under **Vault → API keys**. For an app you signed in to, connect it again and choose **Read and change**, or switch on deleting, as the message says. - **429**: the rate limit was reached; the assistant should wait the number of seconds it is told. ## Related topics - [API Reference](https://docs.envocal.ai/api-reference/) - [Tools guide](https://docs.envocal.ai/api-reference/tools-guide/) - [Your account](https://docs.envocal.ai/account/) - [Vault](https://docs.envocal.ai/vault/)