ragleap-integrations

Install

Nothing to configure at install time: servers and the allowlist are built in your code, never read from the environment.

pip install ragleap-integrations
# or, with uv
uv add ragleap-integrations

What this is (and isn't)

ragleap-integrations v0.1.0 is an MCP (Model Context Protocol) client over Streamable HTTP only. The owner configures servers and an exact server.tool allowlist; the model only supplies a tool's JSON arguments, never a URL, a token or a tool outside the allowlist. It does not own a tool-calling loop — that is ragleap-agents's job.

Not supported in this version: stdio (it launches a subprocess), the deprecated HTTP+SSE transport, sampling/elicitation/roots (a server asking for client input gets a clear “unsupported” result), resources, prompts, subscriptions and OAuth. Connectors, code execution and HTTP fetch are deliberately not included: each needs its own security design pass.

Quick start

from ragleap_integrations import McpConfig, McpServerConfig, make_mcp_tools

config = McpConfig(
    servers=[McpServerConfig("deepwiki", "https://mcp.deepwiki.com/mcp")],  # token="..." if a server needs one
    allowed_tools=["deepwiki.read_wiki_structure"],
)
tools = make_mcp_tools(config)  # discovers the allowlisted tools once (tools/list)

openai_tools = [t.to_openai_schema() for t in tools]  # or t.to_gemini_schema()
result = tools[0].call(repoName="sqlite/sqlite")
print(result.success, result.result)  # True {"text": "..."}

Tools are exposed as <server>__<tool> (characters outside letters, digits, _ and - become _, at most 64 characters). To keep server-controlled text out of the model's context entirely, supply the descriptions and schemas yourself:

from ragleap_integrations import McpToolSpec

spec = McpToolSpec(
    server="deepwiki", name="read_wiki_structure",
    description="List the documentation topics of a GitHub repository.",
    parameters={"type": "object", "properties": {"repoName": {"type": "string"}}, "required": ["repoName"]},
)
tools = make_mcp_tools(config, specs=[spec])  # nothing is sent over the network at setup

Full public API

Version history

Real design decisions & findings

Each of these was decided or found before release, not retrofitted.

• ✓ shipped
  The owner decides, the model only supplies arguments. Servers, tokens and an exact server.tool allowlist come from your code; the model never picks a URL, a token or a tool outside the list.
• ✓ shipped
  A wall-clock deadline that actually holds. A test showed a server sending one byte every 0.2 s kept a plain read blocked for 80 s against a 3 s deadline, because every byte arrived inside the per-operation timeout. A watchdog that shuts the socket down at the deadline (and sets a flag, since the read then looks like a normal end of response) fixes it, and is tested over real TLS.
• ✓ shipped
  No server text in errors. Failures carry a constant message plus, at most, an HTTP status or a JSON-RPC error code, so a hostile server cannot put instructions into an error result.
• ✓ shipped
  The live check found a real bug. The first detection rule treated any JSON-RPC error on a 400 as proof of a modern server; DeepWiki's own -32600 rejection broke it. Only -32020, -32021 and -32022 count as recognized modern errors now, and a failed fallback still shows the first reply's code. The new tests fail on the old code.
• ✓ shipped
  A CodeQL alert was reproduced before it was fixed. py/insecure-protocol flagged the transport because two test contexts reached it without a TLS floor in a place the analyzer follows. It was reproduced locally with the CodeQL CLI running only that query (1 result), the test helper was fixed, and the same run returned 0. No production change.
• not live-verified
  The modern path and several details. The modern 2026-07-28 request flow, x-mcp-header mirroring, the location of a -32022 error's supported-version list, bearer-token authentication, plain JSON responses and pagination follow the public specification and are covered by tests against fakes only. Treat them as best-effort until confirmed live.
• deliberately deferred
  stdio, code execution, HTTP fetch and connectors. Each needs its own security design pass and is not included.

Known limitations

• On a legacy server every tool call performs a full initialize handshake (three requests) and never closes the session.
• A HeaderMismatch error is reported, not retried after re-reading the tool list.
• Only text content is returned; other content types are counted and omitted.
• Server-supplied text (descriptions, schemas, results) is untrusted and is not screened for prompt injection.
• ragleap_tools.Tool.call in ragleap-tools 0.4.0 cannot take an argument literally named self.
• Not safe to share one client between threads while calls are running.