Give trusted external agents a controlled tool interface to Asistn.

Architecture

How the MCP wrapper fits around the workspace API

MCP does not bypass tenant boundaries or read the database directly. It proxies the existing /api/v1 endpoints with configured workspace tokens.

Hermes / External Agent
  -> MCP client
  -> http://asistn-mcp:3010/mcp
  -> Asistn MCP Server
  -> http://app:3006/api/v1/*
  -> Asistn workspace API

Connect

MCP endpoint and client authentication

External agents connect to the Streamable HTTP MCP endpoint. The agent must send the MCP server bearer token, not a workspace API token.

POST http://asistn-mcp:3010/mcp
Authorization: Bearer $ASISTN_MCP_SERVER_TOKEN

curl http://asistn-mcp:3010/healthz

Token

Create and install ASISTN_MCP_SERVER_TOKEN

This is an internal bearer secret for the MCP service. It is generated by you, installed into the production .env file, and used by trusted MCP clients.

TOKEN='paste_generated_token_here'
ENV_FILE='/opt/asistn/Agentic CRM/.env'

if grep -q '^ASISTN_MCP_SERVER_TOKEN=' "$ENV_FILE"; then
  sed -i "s|^ASISTN_MCP_SERVER_TOKEN=.*|ASISTN_MCP_SERVER_TOKEN=$TOKEN|" "$ENV_FILE"
else
  printf '\nASISTN_MCP_SERVER_TOKEN=%s\n' "$TOKEN" >> "$ENV_FILE"
fi

cd '/opt/asistn/Agentic CRM'
docker compose -f docker-compose.prod.yml up -d mcp

Configuration

Environment variables

Production config lives in .env on the server. Token JSON is not checked into the repository.

ASISTN_MCP_SERVER_TOKEN=long_random_internal_bearer_token
ASISTN_MCP_WORKSPACES=[{"slug":"klaser","tokenEnv":"ASISTN_API_TOKEN_KLASER"},{"slug":"safencare","tokenEnv":"ASISTN_API_TOKEN_SAFENCARE"}]
ASISTN_API_TOKEN_KLASER=asistn_live_xxx
ASISTN_API_TOKEN_SAFENCARE=asistn_live_xxx

ASISTN_BASE_URL=http://app:3006
ASISTN_MCP_PORT=3010
ASISTN_MCP_DEFAULT_WORKSPACE=klaser
ASISTN_MCP_READ=true
ASISTN_MCP_WRITE=false
ASISTN_MCP_SEND_MESSAGES=false
ASISTN_MCP_DELETE=false
ASISTN_MCP_ALLOWED_ORIGINS=

Permissions

Tool registration is controlled at startup

Permissions decide which MCP tools exist. If a tool is disabled, agents do not see it in list_tools.

ASISTN_MCP_READ=true
ASISTN_MCP_WRITE=false
ASISTN_MCP_SEND_MESSAGES=false
ASISTN_MCP_DELETE=false

ASISTN_MCP_READ=true
ASISTN_MCP_WRITE=true
ASISTN_MCP_SEND_MESSAGES=false
ASISTN_MCP_DELETE=false

ASISTN_MCP_READ=true
ASISTN_MCP_WRITE=true
ASISTN_MCP_SEND_MESSAGES=true
ASISTN_MCP_DELETE=false

Tools

Available MCP tools

Tool results are returned as JSON text content so MCP clients can inspect and pass them into their own reasoning loop.

Examples

Common agent flows

These examples describe how an external agent should use the tools once it has connected to the MCP endpoint.

1. list_workspaces {}
2. check_all_workspaces_health {}
3. For each workspace:
   - get_analytics { "workspace": "klaser" }
   - list_contacts { "workspace": "klaser", "status": "open", "limit": 50 }
   - get_content_insights { "workspace": "klaser", "days": 30, "limit": 50 }

1. list_contacts { "workspace": "klaser", "q": "6281234567890", "limit": 5 }
2. get_contact { "workspace": "klaser", "contact_id": "CONTACT_ID" }
3. get_conversation { "workspace": "klaser", "contact_id": "CONTACT_ID", "limit": 100 }
4. get_agent_memory { "workspace": "klaser", "contact_id": "CONTACT_ID", "limit": 50 }

push_lead {
  "workspace": "klaser",
  "phone": "6281234567890",
  "name": "Albert",
  "source": "agentic_marketing",
  "external_id": "meta_lead_123",
  "intent": "consultation",
  "ad_source": {
    "platform": "meta",
    "campaign": "k-laser-leadgen"
  },
  "meta_data": {
    "tags": ["meta-lead", "k-laser"]
  }
}

Security

Operational security checklist

Treat the MCP service as a privileged internal integration. It can aggregate multiple workspace tokens in one process.

Troubleshooting

Common failures and what they mean