Connect external agents with the MCP server
The Tealfabric MCP server lets an external agent call your workspace. Cursor, Claude, Lovable, Grok Bot, and MCP Inspector attach to one HTTPS address and receive the tealfabric_* tools for connectors, integrations, WebApps, ProcessFlow, and Documents.
Document information
| Field | Value |
|---|---|
| Canonical URL | /docs/07_ai-agents-and-mcp/32_connect-external-agents-mcp-server |
| Version (published date) | 2026-11-13 |
| Tags | mcp, mcp-server, api-keys, agents |
Which MCP surface you mean
Tealfabric has three MCP surfaces. Use this page when an agent outside Tealfabric should call your workspace.
| Surface | Who calls whom | Where to read |
|---|---|---|
| MCP server | An external agent calls your workspace at POST /mcp | This page and the MCP server tool reference |
| Trace AI tools | Trace AI, inside the console, calls skills-gated tools such as load_platform_skill | Trace AI Agent and the MCP tool catalog |
Remote MCP connector (remote-mcp-1.0.0) | Tealfabric calls a vendor MCP URL through an Integration | Remote MCP Connector Guide |
The MCP server does not load platform skills. Its tool list is fixed for the API key. Chat at /api/v1/mcp* is the in-console agent API and is a different address.
Address and authentication
Point the client at:
https://<your-tealfabric-host>/mcp
On the public Tealfabric service that address is https://tealfabric.io/mcp. The path is /mcp on the API host. It is not under /api/v1.
Send the workspace API key on every request:
| Header | Value |
|---|---|
X-API-Key | The full key, for example tf_live_… or tf_test_… |
Authorization | Bearer followed by the same key, when the key starts with tf_ |
The workspace comes from the key. A tenant_id argument on a document tool is ignored.
Cloud agents such as Grok Bot must use a public HTTPS URL. An address on localhost or a private network is unreachable from that cloud.
Create the API key
A Tenant admin creates the key.
- Open API Keys and choose Create API Key.
- Name the key for one agent or one machine. Copy the secret when it is shown. The full value is shown once.
- Select scopes for the work that agent should do. Details are in API key scopes for the MCP server.
- Store the key in the client’s secret or header field. Keep it out of chat text, source files, and screenshots.
Production workspaces issue keys that start with tf_live_. Sandbox workspaces issue keys that start with tf_test_. See API key management.
API key scopes for the MCP server
The MCP server checks two layers.
| Layer | Scope | What it allows |
|---|---|---|
| Protocol | mcp.read | Discover the server, initialize, and tools/list |
| Protocol | mcp.write | tools/call |
| Workspace data | Domain scopes below | The REST call behind each tool |
On the Create API Key screen the protocol scopes are labeled MCP Protocol - Read (discover / tools/list) and MCP Protocol - Write (tools/call). Select both. A key that has mcp.write can also list tools. A key that has only mcp.read can list tools and cannot call them.
Each tool then calls the workspace API with the same key, so the key also needs the domain scope for that action:
| Tools | Scope on the API key |
|---|---|
| List or read integrations | integrations.read |
| Create or update integrations | integrations.write |
| Delete an integration | integrations.delete |
tealfabric_execute_integration | integrations.execute |
| List or read WebApps | webapps.read |
| Create, update, publish, unpublish, version, or delete WebApps | webapps.write |
| List processes and steps | processflow.read |
| Create, update, retire, or delete processes and steps | processflow.write |
tealfabric_execute_process | processflow.execute |
| List, read, or download documents | documents.read |
| Write, upload, move, or delete documents | documents.write |
| List connectors and check OAuth2 | connectors.read |
tealfabric_test_connector | connectors.write |
All Operations (Full Access) (*) covers the protocol scopes and every domain scope, including connectors.read, connectors.write, and integrations.execute. Those three scopes are not separate checkboxes on the API Keys screen. Use * on a dedicated MCP key when the agent needs the connector tools or tealfabric_execute_integration. Otherwise select only the checkboxes for the areas that agent should touch, and leave connector and integration-execute tools unused.
Connect a client
Use the same URL and the same X-API-Key header in every client that supports a remote MCP server.
Cursor
Add a remote MCP server named tealfabric. In mcp.json:
{
"mcpServers": {
"tealfabric": {
"url": "https://tealfabric.io/mcp",
"headers": {
"X-API-Key": "tf_live_…"
}
}
}
}
Replace the host when your workspace is not on https://tealfabric.io.
Claude and Lovable
Add a remote MCP server with the URL https://<your-tealfabric-host>/mcp and the header X-API-Key. Put the key in the client’s header or secret field.
Grok Bot
Add a custom MCP server and set the server URL to https://<your-tealfabric-host>/mcp. Supply the API key through Grok’s secret or header card. The URL must be public HTTPS. After the server attaches, tools/list returns the tealfabric_* tools.
MCP Inspector
Point Inspector at the same URL and send X-API-Key. Use it to confirm tools/list and one read call before you connect a production agent.
Desktop app that only starts a local program
Some desktop hosts start a local process and do not accept an HTTPS MCP URL. That host can run the program tealfabric-mcp-server with:
| Variable | Required | Meaning |
|---|---|---|
TEALFABRIC_API_KEY | Yes | The same API key |
TEALFABRIC_API_URL | No | API origin. Default is https://tealfabric.io |
{
"mcpServers": {
"tealfabric": {
"command": "tealfabric-mcp-server",
"env": {
"TEALFABRIC_API_KEY": "tf_live_…",
"TEALFABRIC_API_URL": "https://tealfabric.io"
}
}
}
}
This program exposes the same tealfabric_* tools. It calls the workspace REST API with the key. It does not listen on /mcp. Prefer the HTTPS URL when the client can use it. tealfabric_upload_document is the exception that needs this local program: it reads file_path from the machine running the process. On the hosted MCP server that path is on the API host, so a laptop path does not upload. For text files from a remote agent, use tealfabric_write_document_text.
Confirm the connection
- The client completes MCP
initializeandtools/list. - Call a read tool that matches the key, such as
tealfabric_list_processesortealfabric_list_webapps. - Call a write tool only after the read succeeds.
A successful read returns JSON text. A failure inside a tool returns text that starts with Error:.
Operate the key
- One key per agent or per machine, so you can revoke one client without stopping the others.
- Grant
mcp.writetogether with the domain scopes that match the actions you accept. Client approval prompts do not replace those scopes. - Delete, publish, execute, and document-write tools run immediately when the key allows them.
- Rotate the key in API Keys, update the client header, then revoke the previous key. See API key security best practices.
Troubleshoot
| What you see | What to change |
|---|---|
401 and UNAUTHORIZED | Send X-API-Key, or Authorization: Bearer with a key that starts with tf_. A console JWT is not an MCP key. |
403 and API key does not have required scope: mcp.read or mcp.write | Edit the key and add MCP Protocol - Read and MCP Protocol - Write, or select All Operations (Full Access). |
tools/list works and a tool returns Error: with status 403 | Add the domain scope for that tool, or use * when the missing scope is connectors.read, connectors.write, or integrations.execute. |
| Grok Bot cannot reach the server | Use the public https://…/mcp URL. A localhost URL is not reachable from Grok Bot. |
Empty tool result or not found | The key’s workspace is the one that owns the record. Create the key in that workspace. |
tealfabric_upload_document cannot read the file | The path is on the MCP process host. Write text with tealfabric_write_document_text, or run tealfabric-mcp-server on the machine that has the file. |