Scripting Layer

Overview

MCP tools return unbounded responses. A single salesforce_opportunities_list call can dump 200KB+ of raw JSON into an agent's context window. Multiply that by the multi-step workflows agents actually run — five, ten, twenty tool calls per task — and the context window fills with data the agent never needed. This is the MCP token bloat problem, and it is the single largest obstacle to running MCP-based agents in production.

MCP Gateway proposes a solution: a scripting layer where skills contain user-authored Python scripts that intercept tool responses before the agent sees them. Instead of the agent receiving 200KB of raw Salesforce records, a script calls the API, filters to the five fields that matter, computes aggregates, and returns 800 bytes of structured insight. The agent made one tool call and got a compact result. It has zero awareness that a script was involved.

Skills are where developers work. A skill package contains guidance (SKILL.md), scripts, and tool-calling interception logic. The scripting layer is the mechanism inside skills that makes token reduction possible — Python scripts that run in sandboxed containers, call raw MCP tools through the gateway SDK, and return compact results. In end-to-end testing, this approach reduces token consumption by 81-98% compared to raw tool responses.

How It Works

Two Paths

MCP Gateway offers two execution paths that coexist in the same skill package. The key distinction is who decides when the script runs and what constraints are enforced.

my-skill/
├── SKILL.md          # Agent reads this for guidance
└── scripts/
    └── hn_digest.py  # Uses mcpgateway-sdk

my-skill/
├── SKILL.md          # Agent guidance (required)
├── workflow.json     # Tool schemas, constraints
└── tools/
    └── summarize_pipeline.py

Gateway SDK

Scripts communicate with the gateway using mcpgateway-sdk, a thin async Python client that auto-configures from environment variables injected by the gateway.

from mcpgateway_sdk.gateway import gateway

# Call a raw MCP tool — gateway handles credentials
result = await gateway.execute_tool("salesforce_opportunities_list", {
    "query": {"q": "SELECT Id, Name, Amount FROM Opportunity"}
})

# Semantic search across all enabled tools
tools = await gateway.search_tools("salesforce accounts", limit=5)

# Cache data for follow-up questions in the same session
await gateway.cache_set("accounts_q1", account_data, ttl=600)
cached = await gateway.cache_get("accounts_q1")

Exposure Modes

Exposure modes control which types of tools the agent can see, per server.

With script_only, the agent cannot call raw REST tools like salesforce_opportunities_list (200KB response). The only way to get Salesforce data is through the curated script tool summarize_pipeline (800-byte response). The gateway enforces this — not the agent's good behavior.

Security

Related