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
FieldValue
Canonical URL/docs/07_ai-agents-and-mcp/32_connect-external-agents-mcp-server
Version (published date)2026-11-13
Tagsmcp, 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.

SurfaceWho calls whomWhere to read
MCP serverAn external agent calls your workspace at POST /mcpThis page and the MCP server tool reference
Trace AI toolsTrace AI, inside the console, calls skills-gated tools such as load_platform_skillTrace AI Agent and the MCP tool catalog
Remote MCP connector (remote-mcp-1.0.0)Tealfabric calls a vendor MCP URL through an IntegrationRemote 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:

HeaderValue
X-API-KeyThe full key, for example tf_live_… or tf_test_…
AuthorizationBearer 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.

  1. Open API Keys and choose Create API Key.
  2. Name the key for one agent or one machine. Copy the secret when it is shown. The full value is shown once.
  3. Select scopes for the work that agent should do. Details are in API key scopes for the MCP server.
  4. 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.

LayerScopeWhat it allows
Protocolmcp.readDiscover the server, initialize, and tools/list
Protocolmcp.writetools/call
Workspace dataDomain scopes belowThe 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:

ToolsScope on the API key
List or read integrationsintegrations.read
Create or update integrationsintegrations.write
Delete an integrationintegrations.delete
tealfabric_execute_integrationintegrations.execute
List or read WebAppswebapps.read
Create, update, publish, unpublish, version, or delete WebAppswebapps.write
List processes and stepsprocessflow.read
Create, update, retire, or delete processes and stepsprocessflow.write
tealfabric_execute_processprocessflow.execute
List, read, or download documentsdocuments.read
Write, upload, move, or delete documentsdocuments.write
List connectors and check OAuth2connectors.read
tealfabric_test_connectorconnectors.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:

VariableRequiredMeaning
TEALFABRIC_API_KEYYesThe same API key
TEALFABRIC_API_URLNoAPI 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

  1. The client completes MCP initialize and tools/list.
  2. Call a read tool that matches the key, such as tealfabric_list_processes or tealfabric_list_webapps.
  3. 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.write together 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 seeWhat to change
401 and UNAUTHORIZEDSend 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.writeEdit 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 403Add 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 serverUse the public https://…/mcp URL. A localhost URL is not reachable from Grok Bot.
Empty tool result or not foundThe key’s workspace is the one that owns the record. Create the key in that workspace.
tealfabric_upload_document cannot read the fileThe 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.

See also