ai-sdk-relayshield

Vercel AI SDK tools and a mandatory pre-execution gate for RelayShield's agentic-security endpoints — MCP server registry risk and AI-agent-sourced credential breach detection.

Install

npm install ai-sdk-relayshield

Tools

import { generateText } from "ai";
import { checkMcpServerRisk, checkPromptInjectionBreach } from "ai-sdk-relayshield";

const result = await generateText({
  model,
  tools: { checkMcpServerRisk, checkPromptInjectionBreach },
  prompt: "Is it safe to connect to the MCP server at https://mcp.example.com/sse? My RelayShield key is rs_live_...",
});

• checkMcpServerRisk — flags known-malicious IOC matches, typosquat domains, and newly-registered domains hosting an MCP server, before an agent connects to or installs it.
• checkPromptInjectionBreach — checks whether an email appears in RelayShield's stolen-session corpus with a suspected-agentic-source marker (a session/token exposure that shows signs of having been captured via a compromised AI agent).

Both tools take apiKey as a call argument rather than reading it from the environment implicitly — a shared agent process can act safely on behalf of multiple callers with different RelayShield keys.

Get a key at api.relayshield.net/developers.

Mandatory gate

Most "AI agent security" checks are optional — the agent can call them, but nothing stops it skipping the call and taking the risky action anyway. relayshieldMcpGate is the other kind: a gate the SDK enforces before a protected action (connecting to or installing an MCP server) can happen at all, built on the Vercel AI SDK's toolApproval option.

import { generateText } from "ai";
import { relayshieldMcpGate } from "ai-sdk-relayshield";

// Attach directly to your own connect/install tool — the gate is scoped by
// which tool key you attach it to, not by matching tool names inside it.
const result = await generateText({
  model,
  tools: { connectMcpServer },
  toolApproval: { connectMcpServer: relayshieldMcpGate },
  prompt,
});

relayshieldMcpGate reads serverUrl/packageName (or server_url/package_name) off the tool's parsed input and returns "denied" to block the call, or undefined to let it proceed — the shape the Vercel AI SDK's per-tool toolApproval function expects.

Properties, all non-negotiable by design:

• An internal exception defaults to "denied", never silently allows — a gate failure must not become a pass.
• Bounded retry applies only to transient upstream failures (timeout/429/5xx) — auth failures, malformed responses, and payment-required states are terminal after one attempt.
• The gate logs the decision, reason codes, check version, target, and timestamp — never keys, payment proofs, or session material.
• The raw connect/install tool should never be bound to the model directly in a real deployment — only route access to it through the gate.

Same normalized policy as langchain-relayshield's RelayShieldMCPGateMiddleware and openai-agents-relayshield's relayshield_mcp_gate — ported rather than imported, so this package has no dependency on either.

License

MIT