HTTP & MCP Backends¶
ToolClad oneshot mode declares three backends: shell commands ([command]), HTTP requests ([http]), and MCP proxy calls ([mcp]). All three share the same governance layer: argument validation, policy gating, output schema validation, and evidence envelopes. The backend determines how the request is dispatched.
Which backends the reference runtimes execute.
[command]and[http]are executed.[mcp]manifests are parsed and validated but not executable: the reference runtimes validate the arguments, applyfield_map, and return adelegation_previewenvelope without contacting any MCP server. Forwarding the call upstream is the job of a hosting runtime such as Symbiont.
HTTP Backend¶
HTTP API tools use an [http] section instead of [command]. The executor constructs an HTTP request from the manifest, executes it, and wraps the response in a standard evidence envelope.
HTTP Manifest Example¶
# tools/slack_post_message.clad.toml
[tool]
name = "slack_post_message"
version = "1.0.0"
description = "Post a message to a Slack channel"
timeout_seconds = 30
risk_tier = "medium"
[tool.cedar]
resource = "Comms::SlackChannel"
action = "post_message"
[args.channel]
type = "string"
required = true
pattern = "^[A-Z0-9]+$"
description = "Slack channel ID"
[args.message]
type = "string"
required = true
sanitize = ["injection"]
description = "Message text to post"
[http]
method = "POST"
url = "https://slack.com/api/chat.postMessage"
headers = { "Authorization" = "Bearer {_secret:slack_token}", "Content-Type" = "application/json" }
body_template = '{"channel": "{channel}", "text": "{message}"}'
success_status = [200]
error_status = [400, 401, 403, 404, 429]
[output]
format = "json"
parser = "builtin:json"
envelope = true
[output.schema]
type = "object"
[output.schema.properties.ok]
type = "boolean"
description = "Whether the API call succeeded"
[output.schema.properties.ts]
type = "string"
description = "Message timestamp (Slack message ID)"
[http] Field Reference¶
| Field | Type | Description |
|---|---|---|
method |
string | HTTP method: GET, POST, PUT, PATCH, DELETE |
url |
string | URL template with {arg} and {_secret:name} placeholders |
headers |
table | Header key-value pairs, supports {_secret:name} |
body_template |
string | Request body template with {arg} placeholders |
success_status |
array | HTTP status codes that indicate success |
error_status |
array | HTTP status codes that indicate known errors |
HTTP Request Construction¶
The executor follows this sequence:
- Expand
{_secret:name}references on the manifest template first -- inurl, everyheadersvalue, andbody_template. Because this happens before any argument is interpolated, an argument value can never introduce a secret reference (theurlvalidator also rejects{and}outright). - Interpolate
{arg_name}placeholders with validated parameter values. Values placed in the URL are percent-encoded (path segments with the path set, query values with the query set); values placed inbody_templateare JSON-escaped. - Set method, headers, and body
- Execute with
timeout_seconds. Redirects are not followed: a 3xx response is surfaced asstatus: "redirect_blocked". - Check response status against
success_status/error_status - Parse the response body with the declared parser, subject to
[output] max_bytes - Validate against
[output.schema](fail-closed: a violation yieldsstatus: "schema_error"with the raw body preserved) - Wrap in an evidence envelope. The envelope's
commandholds the unexpanded template ("<METHOD> <http.url as written in the manifest>"), never the expanded URL, so secrets never reach the agent or the evidence store.
[http] manifests are treated as network_egress = true: every url, scope_target, ip_address, or cidr argument must set block_internal = true or the manifest is refused at load.
Secrets Injection¶
The {_secret:name} syntax references secrets that are resolved at invocation time. Secrets never appear in the manifest, MCP schema, or LLM context.
[http]
url = "https://api.example.com/v1/{endpoint}?key={_secret:api_key}"
headers = { "Authorization" = "Bearer {_secret:bearer_token}" }
Resolution order in the reference runtimes:
- The file named by
TOOLCLAD_SECRETS_FILE(preferred): a TOML file withname = "value"entries at top level. Its permissions are checked and it is rejected if group- or other-readable. When present, the file wins. - The
TOOLCLAD_SECRET_<NAME>environment variable of the runtime's own process.
A missing secret is a hard error. Secrets are never placed in a child process environment (TOOLCLAD_SECRET_* is stripped from every spawn), never appear in the envelope's command, and -- because expansion happens before argument interpolation -- can never be referenced from an argument value. A hosting runtime such as Symbiont may substitute its own secret store (Vault/OpenBao); that integration is outside the reference runtimes.
The agent proposes slack_post_message(channel="C01234", message="hello"). The executor injects the bearer token from the secret store. The agent never sees the token.
Status Code Validation¶
- Status in
success_status: parse response, return results. - Status in
error_status: return error envelope with status code and response body for agent self-correction. - Status not in either list: return error envelope with "unexpected status code" message.
- Any 3xx: redirects are not followed; the envelope status is
redirect_blocked. - 4xx responses are classified
client_errorand 5xxserver_errorin the envelope.
HTTP GET Example¶
# tools/ip_lookup.clad.toml
[tool]
name = "ip_lookup"
version = "1.0.0"
description = "Look up geolocation data for an IP address"
timeout_seconds = 10
risk_tier = "low"
[args.ip]
type = "ip_address"
required = true
# [http] manifests are network egress: block_internal is mandatory at load.
block_internal = true
description = "IP address to look up"
[http]
method = "GET"
url = "https://ipapi.co/{ip}/json/" # {ip} is percent-encoded as a path segment
success_status = [200]
error_status = [429]
[output]
format = "json"
parser = "builtin:json"
envelope = true
[output.schema]
type = "object"
[output.schema.properties.city]
type = "string"
[output.schema.properties.region]
type = "string"
[output.schema.properties.country_name]
type = "string"
[output.schema.properties.org]
type = "string"
description = "ISP or organization"
MCP Proxy Backend¶
Not executable by the reference runtimes. An
[mcp]manifest loads, validates, and produces an MCP schema, butexecutereturns adelegation_previewenvelope containing the upstream server name, tool name, and the field-mapped arguments. No MCP server is contacted. Steps 4-6 of the execution flow below are performed by a hosting runtime, not by the reference CLIs or libraries.
The MCP proxy backend wraps an existing MCP server tool in a ToolClad manifest. The manifest applies stricter validation and policy gating on top of the upstream tool's permissive schema.
Why Proxy MCP Tools?¶
MCP tools from marketplaces and third-party servers have permissive JSON Schemas. A GitHub MCP tool might accept any string for a repository name. A database MCP tool might accept any SQL query.
The ToolClad manifest constrains these inputs with the full type system (regex patterns, enums, scope checks) and subjects every invocation to Cedar policy evaluation. Instead of trusting a marketplace MCP tool's self-declared schema, you wrap it in a .clad.toml that defines the contract you trust.
Without proxy: Agent -> MCP Server (permissive schema, no Cedar)
With proxy: Agent -> ToolClad (strict types, Cedar) -> MCP Server
MCP Proxy Manifest Example¶
# tools/github_create_issue.clad.toml
[tool]
name = "github_create_issue"
version = "1.0.0"
description = "Create a GitHub issue in an allowed repository"
timeout_seconds = 30
risk_tier = "medium"
[tool.cedar]
resource = "Dev::GitHubRepo"
action = "create_issue"
[mcp]
server = "github-mcp"
tool = "create_issue"
[args.repo]
type = "string"
required = true
pattern = "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+$"
description = "Repository in owner/repo format"
[args.title]
type = "string"
required = true
sanitize = ["injection"]
description = "Issue title"
[args.body]
type = "string"
required = false
description = "Issue body (markdown)"
[args.labels]
type = "string"
required = false
pattern = "^[a-zA-Z0-9_, -]+$"
description = "Comma-separated label names"
[output]
format = "json"
parser = "builtin:json"
envelope = true
[output.schema]
type = "object"
[output.schema.properties.number]
type = "integer"
description = "Created issue number"
[output.schema.properties.url]
type = "string"
description = "URL of the created issue"
[output.schema.properties.state]
type = "string"
description = "Issue state (open)"
[mcp] Field Reference¶
| Field | Type | Description |
|---|---|---|
server |
string | Named MCP server connection from symbiont.toml |
tool |
string | Upstream MCP tool name to invoke |
field_map |
table | Optional: map ToolClad arg names to upstream param names |
The server field references a named MCP server in the runtime configuration:
# symbiont.toml
[mcp.servers.github-mcp]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${vault:github/api-token}" }
Field Mapping¶
When ToolClad argument names differ from the upstream MCP tool's parameter names:
[mcp]
server = "github-mcp"
tool = "create_issue"
[mcp.field_map]
repo = "repository" # ToolClad "repo" -> upstream "repository"
labels = "label_names" # ToolClad "labels" -> upstream "label_names"
Unmapped fields pass through with the same name. This decouples the ToolClad contract from the upstream tool's naming conventions. You can rename parameters to be clearer for the agent without changing the upstream tool.
MCP Proxy Execution Flow¶
- ToolClad validates all arguments against the manifest's type system (stricter than upstream)
- The policy gate runs (
human_approval/risk_tierdeny-by-default); Cedar evaluation, e.g. "this agent can only create issues inThirdKeyAI/*repos", is external to the reference runtimes - Executor maps validated arguments to the upstream tool's expected names via
field_mapand -- in the reference runtimes -- returns adelegation_previewenvelope here - (hosting runtime) Forwards the call to the MCP server referenced by
server - (hosting runtime) Response is parsed and validated against
[output.schema] - (hosting runtime) Wrapped in evidence envelope with audit trail
Proxy for Database MCP¶
# tools/db_query.clad.toml -- Govern a database MCP tool
[tool]
name = "db_read_query"
version = "1.0.0"
description = "Execute a read-only SQL query"
timeout_seconds = 30
risk_tier = "medium"
[tool.cedar]
resource = "Data::Database"
action = "read_query"
[mcp]
server = "postgres-mcp"
tool = "query"
[args.sql]
type = "string"
required = true
pattern = "^SELECT\\s"
sanitize = ["injection"]
description = "SQL SELECT query (read-only)"
[args.database]
type = "enum"
required = true
allowed = ["analytics", "reporting", "staging"]
description = "Target database"
[mcp.field_map]
sql = "query"
database = "db_name"
[output]
format = "json"
parser = "builtin:json"
envelope = true
[output.schema]
type = "object"
[output.schema.properties.rows]
type = "array"
description = "Query result rows"
[output.schema.properties.row_count]
type = "integer"
The upstream postgres-mcp tool accepts any query string. The ToolClad manifest constrains it to SELECT statements only, limits which databases can be targeted, and gates every invocation through Cedar.
Shared Guarantees¶
What the reference runtimes enforce for each backend:
| Guarantee | Shell | HTTP | MCP Proxy |
|---|---|---|---|
| Argument validation | Yes | Yes | Yes |
Policy gate (human_approval, risk_tier) |
Yes | Yes | Yes |
| Cedar policy evaluation | External | External | External |
Scope enforcement (scope_check) |
Yes | Yes | Yes |
Egress lint (block_internal required) |
When network_egress / egress binary |
Always | No |
| Output schema validation (fail-closed) | Yes | Yes | Not applicable (no upstream response) |
Output cap (max_bytes) |
Yes | Yes | Not applicable |
| Timeout enforcement | Yes | Yes | Not applicable |
| Evidence envelope | Yes | Yes | delegation_preview only |
The backend is an implementation detail of dispatch; argument validation and the policy gate are the same for all three.