MCP Bindings (Model Context Protocol)

Overview

A MCP binding exposes a SpEL script as a tool in the Model Context Protocol (MCP). This allows AI agents — such as GitHub Copilot, Claude, ChatGPT, or any MCP-compatible client — to discover and invoke tSM scripts through a standardised tool-calling interface.

When a script is published via MCP binding, the AI agent sees it as a typed tool with:

• a name and description (derived from the script's metadata),
• a JSON Schema for input parameters (derived from paramsFormCode),
• a JSON Schema for the result (derived from resultFormCode).

The agent can then call the tool, passing validated parameters, and receive the script's result — all without any custom code on the AI side.

Bindings are organized into servers (tool groups). Each server exposes its own MCP endpoint, so different AI agents or contexts can connect to different subsets of tools.

---

How it works

1. Discovery — the agent connects to a specific server endpoint (e.g. $tsmBase/api/v2/mcp/finance). The tools/list response contains only the tools assigned to that server. Each tool's inputSchema is generated from the script's paramsFormCode and the description from the script's metadata.
2. Routing — the API Gateway reads the script's microservice field and routes the call to the correct backend microservice automatically.
3. Invocation — the gateway validates the arguments against the paramsFormCode JSON Schema, then the target microservice executes the script and returns the result.
4. Result typing — if resultFormCode is defined, the response schema is included in the tool catalog so the agent knows the shape of the returned data.

---

Servers (tool groups)

Every MCP binding belongs to a server — a logical group of tools exposed on its own MCP endpoint. Servers let you partition tools by domain, team, or use-case so that each AI agent only sees the tools relevant to its task.

Server code	Endpoint	Example tools
finance	$tsmBase/api/v2/mcp/finance	tsm.finance.convert, tsm.finance.balance
operations	$tsmBase/api/v2/mcp/operations	tsm.ticket.create, tsm.order.status
reporting	$tsmBase/api/v2/mcp/reporting	tsm.report.monthly, tsm.report.sla

Servers are implicit — they are derived from the unique server values across all binding rows. There is no separate server register; simply set the same server value on each binding row that should belong to the same group.

If a binding row has no server value, it is exposed on the default server endpoint ($tsmBase/api/v2/mcp).

---

Register-row schema (Scripts.Bindings.McpInvocations)

Bindings are configured in the register "Scripts / Bindings / MCP Invocations" (internal code Scripts.Bindings.McpInvocations).

Field	Type	Required	Default	Description
fullName	string	✔	–	The MCP tool name exposed to agents (e.g. tsm.finance.convert).
script	string	✔	–	LOV to the target script code in the Scripts register.
server	string	–	–	Server (tool group) this binding belongs to. Determines the endpoint path: /api/v2/mcp/<server>. When empty, the tool is exposed on the default /api/v2/mcp endpoint.
description	string	–	–	Override for the tool description shown to the AI agent. Falls back to the script's description field.

---

Role of paramsFormCode and resultFormCode

MCP bindings derive the most value from the script's form definitions, because the MCP protocol requires explicit JSON Schemas for tool inputs and outputs:

Script field	Effect on MCP binding
paramsFormCode	The form's JSON Schema becomes the tool's inputSchema. The AI agent sees field names, types, descriptions, and constraints — enabling it to construct valid calls autonomously. Parameters are validated before execution.
resultFormCode	The form's JSON Schema becomes the tool's output schema. The agent can parse and reason about the result structure without guessing.

Because a tSM Form is both a JSON Schema (data model) and a UI definition, a single artefact serves triple duty:

1. AI contract — the agent reads the schema to understand what parameters to pass and what result to expect.
2. Validation — incoming arguments are checked against the schema before the script runs; malformed calls are rejected.
3. Documentation — field labels and descriptions from the form appear as tool documentation in the agent's UI.

warning

Scripts without paramsFormCode can still be bound via MCP, but the resulting tool will have no input schema. Most AI agents will struggle to call it correctly. Always define a parameter form for MCP-exposed scripts.

---

Example

Script — Finance.Convert with:

• paramsFormCode → a form defining amount (number, required), sourceCurrency (string), targetCurrency (string)
• resultFormCode → a form defining convertedAmount (number), rate (number)

Binding row

{
  "fullName":    "tsm.finance.convert",
  "script":      "Finance.Convert",
  "server":      "finance",
  "description": "Convert an amount between currencies using the current exchange rate."
}

What the AI agent sees (tool catalog entry):

{
  "name": "tsm.finance.convert",
  "description": "Convert an amount between currencies using the current exchange rate.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "amount":         { "type": "number", "description": "Amount to convert" },
      "sourceCurrency": { "type": "string", "description": "ISO 4217 source currency code" },
      "targetCurrency": { "type": "string", "description": "ISO 4217 target currency code" }
    },
    "required": ["amount", "sourceCurrency", "targetCurrency"]
  }
}

Agent calls → tools/call with { "amount": 100, "sourceCurrency": "USD", "targetCurrency": "CZK" }

Response → { "convertedAmount": 2200, "rate": 22.0 }

---

MCP server setup

The MCP server is part of the tSM API Gateway microservice. It starts automatically with the gateway and exposes each server (tool group) on its own endpoint:

Default (no server)	Named server
$tsmBase/api/v2/mcp	$tsmBase/api/v2/mcp/<server>

For example, bindings with "server": "finance" are available at $tsmBase/api/v2/mcp/finance.

When the agent calls a tool, the API Gateway routes the request to the correct backend microservice based on the script's microservice field. This means the agent only needs to know the gateway URL — it never connects to individual microservices directly.

An AI agent connecting to /api/v2/mcp/finance will only see the tools belonging to the finance server in its tools/list response. This keeps the tool catalog focused and reduces noise for the agent.

Embedded SpEL tools (spel server)

The API Gateway provides a built-in MCP server at $tsmBase/api/v2/mcp/spel with tools for working with SpEL expressions directly. These tools are always available and do not require any binding configuration.

Tool	Description	Key parameters
autocomplete	Get autocomplete suggestions for a SpEL expression at a given cursor position.	expression, caretPosition, microservice, optional context
validate	Validate SpEL expression syntax without executing it.	expression, microservice, optional context
evaluate	Evaluate a raw SpEL expression or execute a configured script by its code.	expression or scriptCode, optional microservice, optional context

The evaluate tool supports two modes:

• Script mode — pass scriptCode (e.g. "Order.Get.Products"). The gateway resolves the script's target microservice automatically; microservice is optional.
• Expression mode — pass a raw expression string. The microservice parameter is required so the gateway knows where to route.

warning

The embedded SpEL tools require at least the Configurator role. Running arbitrary SpEL expressions is a powerful operation — standard users cannot access these tools.

---

Registering the MCP server in an AI agent

Once bindings are configured and the tSM API Gateway is running, you need to register it as a tool source in your AI agent / IDE. Below are examples for the most common clients.

VS Code (GitHub Copilot)

Add the server to your .vscode/mcp.json (workspace-level) or User Settings (settings.json → mcp.servers):

// .vscode/mcp.json
{
  "servers": {
    "tsm-finance": {
      "type": "http",
      "url": "https://tsm.example.com/api/v2/mcp/finance",
      "headers": {
        "Authorization": "Bearer ${input:tsmToken}"
      }
    },
    "tsm-operations": {
      "type": "http",
      "url": "https://tsm.example.com/api/v2/mcp/operations",
      "headers": {
        "Authorization": "Bearer ${input:tsmToken}"
      }
    },
    "tsm-spel": {
      "type": "http",
      "url": "https://tsm.example.com/api/v2/mcp/spel",
      "headers": {
        "Authorization": "Bearer ${input:tsmToken}"
      }
    }
  }
}

• type — use http (Streamable HTTP transport).
• url — the full MCP endpoint URL including the server code.
• headers — pass the Bearer token for authentication (see Authentication & authorization below).
• ${input:tsmToken} — VS Code prompts you for the value on first use; you can also hard-code a service-account token for CI/CD scenarios.

After saving, Copilot Chat discovers the tools automatically. Type # in the chat input to see the tool list.

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "tsm-finance": {
      "url": "https://tsm.example.com/api/v2/mcp/finance",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Cursor

Open Settings → MCP and add a new server:

Field	Value
Name	tsm-finance
Type	http
URL	https://tsm.example.com/api/v2/mcp/finance

Set the Authorization header to Bearer <your-token> in the advanced settings.

Any MCP-compatible client

The tSM MCP server implements the standard MCP Streamable HTTP transport. Any client that supports this transport can connect by pointing to the URL and passing an Authorization header.

tip

Register one server entry per tool group. If you have three servers (finance, operations, reporting), create three entries in your agent config — each pointing to its own $tsmBase/api/v2/mcp/<server> URL. This way the agent only loads the tools it needs for the current context.

Add the spel server for development-time tools (autocomplete, validate, evaluate).

---

Authentication & authorization

tSM MCP endpoints are authenticated — every request must carry credentials.

Bearer token (recommended)

Pass a tSM JWT / OAuth 2 access token in the Authorization header:

Authorization: Bearer <access-token>

This is the recommended and default authentication method. The token identifies the user; all execPrivilege and role-based access rules are evaluated against this user's session.

How to obtain a token depends on your tSM deployment:

Method	Use-case
OAuth 2 client credentials	For service accounts and CI/CD pipelines. Request a token from the tSM identity provider using client_credentials grant.
OAuth 2 authorization code	For user-facing applications where the end-user authenticates interactively.
Personal access token	If your tSM deployment supports PATs, generate one in the user profile and use it as the Bearer value.

Basic authentication (restricted)

Authorization: Basic <base64(username:password)>

warning

Basic authentication is disabled by default. It is only available if the tSM backend has been explicitly configured to allow it. Use Basic auth only for local development or legacy integrations that cannot handle Bearer tokens. Never use Basic auth in production without TLS.

Authorization rules

Once authenticated, the standard tSM authorization model applies:

• execPrivilege on the script — if set, the user's roles must include this privilege.
• Role-based access — entity-level and field-level permissions are enforced during script execution, just like any other API call.
• Tenant header — in multi-tenant deployments, the X-Tenant-Id header must be present (same as REST bindings).

---

Transaction behavior

Each MCP tool call runs in its own database transaction, similar to REST bindings.

• If the script modifies entities, those changes are committed when the call completes successfully.
• If the script throws an exception, the transaction is rolled back and the agent receives an error response.
• External calls made during the script (REST, SOAP, Kafka) are not part of the transaction — see Transactions overview for strategies.

For the full discussion on transactions in SpEL, see SpEL and Transactions.

---

Security

MCP tool calls are subject to the full tSM security model — see Authentication & authorization above for transport-level details. At the script level:

• execPrivilege — if the script declares a required privilege, the caller's token must carry it.
• Role-based access — entity and field-level permissions are enforced during execution.
• Audit trail — every tool call is logged with the authenticated user, timestamp, and traceId.

---

Good practices

• Always define paramsFormCode — without an input schema, the AI agent has to guess parameters, leading to frequent errors.
• Use descriptive field labels — the agent reads the form's labels and descriptions as tool documentation; clear names lead to better AI performance.
• Define resultFormCode — helps the agent parse responses and chain tools together reliably.
• Keep tool names stable — agents may reference tools by name in saved prompts or workflows; renaming breaks those references.
• Group related tools into a server — use the server field to create focused tool groups. An agent working on finance tasks should not see 200 unrelated tools; connect it to $tsmBase/api/v2/mcp/finance instead.
• Use a consistent naming convention for servers — short, lowercase, domain-oriented codes (finance, operations, reporting) work best.

---

See also

• Script (reference) — script definition, types, parameter forms, and attributes.
• SpEL Console — developing and debugging SpEL scripts interactively.
• Event Bindings — trigger scripts on entity lifecycle events.
• Script-to-Script Bindings — call one script from another.
• REST Bindings — expose scripts as HTTP endpoints.
• SpEL and Transactions — how transactions affect SpEL scripts.
• Transactions overview — general transaction concepts and strategies.