Agent Frameworks - Runlayer

Point an agent framework at a Runlayer MCP proxy URL and your agent calls MCP tools as usual — Runlayer applies policy, scanning, and identity in the middle. Pick your framework below.

To instrument the tools your agent runs itself (shell, local functions, non-proxied MCP) and stream the full conversation into Sessions, use the Hooks SDK instead. Many agents use both.

Copy Prompt

Paste this into your coding agent to connect an existing project to Runlayer. It covers every framework on this page — the agent picks the right one:

Read the Runlayer agent framework integration docs at https://docs.runlayer.com/agent-frameworks and connect my agent to Runlayer-hosted MCP servers.

Claude Agent SDK
Vercel AI SDK
OpenAI Agents SDK
Google ADK

The Claude Agent SDK supports MCP servers natively. Pass Runlayer MCP servers to query() and allow their tools with allowedTools.

Installation

npm install @anthropic-ai/claude-agent-sdk

Set your Anthropic API key:

export ANTHROPIC_API_KEY=your-anthropic-key

HTTP Transport (Production)

Use HTTP transport for production deployments with remote MCP servers. The TypeScript and Python SDKs share the same mcpServers / mcp_servers and allowedTools / allowed_tools shape:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Get info about the vercel/ai repository",
  options: {
    mcpServers: {
      github: {
        type: "http",
        url: "https://mcp.runlayer.com/github-a1b2c3/mcp",
        headers: {
          "x-runlayer-api-key": process.env.RUNLAYER_API_KEY!
        }
      }
    },
    allowedTools: ["mcp__github__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

The server key sets the tool prefix. A server named github exposes tools as mcp__github__<tool>, so mcp__github__* allows all tools from that server.

Multiple MCP Servers

Add each server to mcpServers and allow each server’s tools:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Create a GitHub issue and a Linear ticket for the bug report",
  options: {
    mcpServers: {
      github: {
        type: "http",
        url: "https://mcp.runlayer.com/github-a1b2c3/mcp",
        headers: { "x-runlayer-api-key": process.env.RUNLAYER_API_KEY! }
      },
      linear: {
        type: "http",
        url: "https://mcp.runlayer.com/linear-d4e5f6/mcp",
        headers: { "x-runlayer-api-key": process.env.RUNLAYER_API_KEY! }
      }
    },
    allowedTools: ["mcp__github__*", "mcp__linear__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Agent Accounts

Use Agent Accounts when your Claude app should authenticate as an agent, not a user API key. Fetch an token, then pass it to Runlayer’s MCP proxy:

import { query } from "@anthropic-ai/claude-agent-sdk";

const tokenResponse = await fetch(`${process.env.RUNLAYER_URL}/api/v1/oauth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.RUNLAYER_CLIENT_ID!,
    client_secret: process.env.RUNLAYER_CLIENT_SECRET!
  })
});

const { access_token: accessToken } = await tokenResponse.json();

for await (const message of query({
  prompt: "List recent GitHub issues",
  options: {
    mcpServers: {
      github: {
        type: "http",
        url: `${process.env.RUNLAYER_URL}/api/v1/proxy/${process.env.SERVER_ID}/mcp`,
        headers: { Authorization: `Bearer ${accessToken}` }
      }
    },
    allowedTools: ["mcp__github__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

For on-behalf-of user calls, exchange the agent token (RFC 8693) with the delegated user’s email as subject_token. accessToken is the agent token minted in the M2M example above:

const userEmail = "alice@example.com"; // the delegated user

const { access_token: oboToken } = await (await fetch(`${process.env.RUNLAYER_URL}/api/v1/oauth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
    actor_token: accessToken,
    actor_token_type: "urn:ietf:params:oauth:token-type:access_token",
    subject_token: userEmail,
    subject_token_type: "urn:runlayer:token-type:user-email"
  })
})).json();

Migrating from the client_credentials OBO shortcut: earlier versions documented passing subject_token / subject_token_type directly on the client_credentials grant. That shape is still accepted for backward compatibility but deprecated — switch to the two-step flow: mint an agent token with client_credentials, then exchange it with grant_type=urn:ietf:params:oauth:grant-type:token-exchange (agent token in actor_token, user identity in subject_token, per RFC 8693 §2.1).

See Agent Account Authentication Recipes for UUID and WorkOS OBO variants.

Resources

The Vercel AI SDK supports MCP servers through the @ai-sdk/mcp package, enabling your AI applications to use MCP tools.

Installation

npm install @ai-sdk/mcp @ai-sdk/openai ai

Connect

HTTP (Production)
stdio (Local)

Use HTTP transport for production deployments with remote MCP servers:

import { experimental_createMCPClient } from '@ai-sdk/mcp';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const mcpClient = await experimental_createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.runlayer.com/github-a1b2c3/mcp',
    headers: {
      'x-runlayer-api-key': 'your-api-key'
    }
  }
});

try {
  const tools = await mcpClient.tools();

  const result = await generateText({
    model: openai('gpt-4o'),
    tools,
    prompt: 'Get info about the vercel/ai repository'
  });

  console.log(result.text);
} finally {
  await mcpClient.close();
}

For local Runlayer MCP servers:

import { experimental_createMCPClient } from '@ai-sdk/mcp';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';

const mcpClient = await experimental_createMCPClient({
  transport: new Experimental_StdioMCPTransport({
    command: 'uvx',
    args: [
      'runlayer',
      '936ac3e8-bb75-428d-8db1-b1f08ff07816',
      '--secret', 'your-secret-key',
      '--host', 'https://mcp.runlayer.com'
    ]
  })
});

Streaming Responses

Use streamText for streaming responses with proper cleanup:

import { experimental_createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

const mcpClient = await experimental_createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.runlayer.com/github-a1b2c3/mcp',
    headers: { 'x-runlayer-api-key': 'your-api-key' }
  }
});

const tools = await mcpClient.tools();

const result = await streamText({
  model: openai('gpt-4o'),
  tools,
  prompt: 'List recent issues in vercel/ai',
  onFinish: async () => {
    await mcpClient.close();
  }
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Multiple MCP Servers

Combine tools from multiple servers:

import { experimental_createMCPClient } from '@ai-sdk/mcp';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const [githubClient, linearClient] = await Promise.all([
  experimental_createMCPClient({
    transport: {
      type: 'http',
      url: 'https://mcp.runlayer.com/github-a1b2c3/mcp',
      headers: { 'x-runlayer-api-key': 'your-api-key' }
    }
  }),
  experimental_createMCPClient({
    transport: {
      type: 'http',
      url: 'https://mcp.runlayer.com/linear-d4e5f6/mcp',
      headers: { 'x-runlayer-api-key': 'your-api-key' }
    }
  })
]);

try {
  const [githubTools, linearTools] = await Promise.all([
    githubClient.tools(),
    linearClient.tools()
  ]);

  const tools = { ...githubTools, ...linearTools };

  const result = await generateText({
    model: openai('gpt-4o'),
    tools,
    prompt: 'Create a GitHub issue and a Linear ticket for the bug report'
  });

  console.log(result.text);
} finally {
  await Promise.all([
    githubClient.close(),
    linearClient.close()
  ]);
}

Next.js API Route

Use in a Next.js API route:

// app/api/chat/route.ts
import { experimental_createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const mcpClient = await experimental_createMCPClient({
    transport: {
      type: 'http',
      url: 'https://mcp.runlayer.com/github-a1b2c3/mcp',
      headers: { 'x-runlayer-api-key': 'your-api-key' }
    }
  });

  const tools = await mcpClient.tools();

  const result = await streamText({
    model: openai('gpt-4o'),
    tools,
    messages,
    onFinish: async () => {
      await mcpClient.close();
    }
  });

  return result.toDataStreamResponse();
}

Resources

The OpenAI Agents SDK supports MCP servers with multiple transport options, enabling Python agents to use MCP tools.

Installation

pip install openai-agents

Connect

Streamable HTTP (Production)
stdio (Local)
Hosted MCP

Use MCPServerStreamableHttp for self-managed MCP servers:

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="GitHub Server",
        params={
            "url": "https://mcp.runlayer.com/github-a1b2c3/mcp",
            "headers": {"x-runlayer-api-key": "your-api-key"},
            "timeout": 10,
        },
        cache_tools_list=True,
    ) as server:
        agent = Agent(
            name="GitHub Assistant",
            instructions="Use GitHub tools to help with repository tasks.",
            mcp_servers=[server],
        )

        result = await Runner.run(
            agent,
            "Get info about the vercel/ai repository"
        )
        print(result.final_output)

asyncio.run(main())

For local Runlayer MCP servers:

from pathlib import Path
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Local Runlayer Server",
    params={
        "command": "uvx",
        "args": [
            "runlayer",
            "936ac3e8-bb75-428d-8db1-b1f08ff07816",
            "--secret", "your-secret-key",
            "--host", "https://mcp.runlayer.com"
        ],
    },
) as server:
    agent = Agent(
        name="Assistant",
        instructions="Help with tasks using local MCP server.",
        mcp_servers=[server],
    )
    result = await Runner.run(agent, "Use the available tools")
    print(result.final_output)

Let OpenAI’s infrastructure call MCP servers:

from agents import Agent, Runner, HostedMCPTool

agent = Agent(
    name="Assistant",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "github",
                "server_url": "https://mcp.runlayer.com/github-a1b2c3/mcp",
                "require_approval": "never",
            }
        )
    ],
)

result = await Runner.run(agent, "Get repository info")
print(result.final_output)

Tool Filtering

Filter which tools to expose:

from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter

async with MCPServerStreamableHttp(
    name="GitHub Server",
    params={"url": "https://mcp.runlayer.com/github-a1b2c3/mcp"},
    tool_filter=create_static_tool_filter(
        allowed_tool_names=["get_repository", "list_issues"]
    ),
) as server:
    agent = Agent(name="Assistant", mcp_servers=[server])
    result = await Runner.run(agent, "Get repo info")
    print(result.final_output)

Multiple MCP Servers

Combine tools from multiple servers:

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="GitHub",
        params={
            "url": "https://mcp.runlayer.com/github-a1b2c3/mcp",
            "headers": {"x-runlayer-api-key": "your-api-key"},
        },
    ) as github_server, MCPServerStreamableHttp(
        name="Linear",
        params={
            "url": "https://mcp.runlayer.com/linear-d4e5f6/mcp",
            "headers": {"x-runlayer-api-key": "your-api-key"},
        },
    ) as linear_server:
        agent = Agent(
            name="Project Manager",
            instructions="Help coordinate GitHub and Linear tasks.",
            mcp_servers=[github_server, linear_server],
        )

        result = await Runner.run(
            agent,
            "Create a GitHub issue and a Linear ticket for the bug"
        )
        print(result.final_output)

asyncio.run(main())

Using MCP Prompts

Fetch prompts from MCP servers:

async with MCPServerStreamableHttp(
    name="Server",
    params={"url": "https://mcp.runlayer.com/server-xyz/mcp"},
) as server:
    # Get available prompts
    prompts = await server.list_prompts()

    # Fetch a specific prompt
    prompt_result = await server.get_prompt(
        "generate_instructions",
        {"focus": "code review", "language": "python"}
    )

    instructions = prompt_result.messages[0].content.text

    agent = Agent(
        name="Code Reviewer",
        instructions=instructions,
        mcp_servers=[server],
    )

Resources

The Google Agent Development Kit (ADK) supports MCP servers, enabling Python agents to use MCP tools and expose ADK tools via MCP.

Installation

pip install google-genai

Connect to an MCP Server

Use MCP servers in ADK agents:

import asyncio
from google import genai
from google.genai import types

async def main():
    client = genai.Client(
        vertexai=False,
        api_key="your-gemini-api-key"
    )

    # Connect to MCP server
    mcp_config = types.LiveConnectConfig(
        mcp_servers=[
            {
                "url": "https://mcp.runlayer.com/github-a1b2c3/mcp",
                "headers": {"Authorization": "Bearer your-token"}
            }
        ]
    )

    async with client.aio.live.connect(
        model="gemini-2.0-flash-exp",
        config=mcp_config
    ) as session:
        # Use MCP tools through the agent
        await session.send("Get info about the vercel/ai repository", end_of_turn=True)

        async for response in session.receive():
            if response.text:
                print(response.text)

asyncio.run(main())

FastMCP servers and Google Cloud Genmedia servers (Imagen, Veo, Chirp, Lyria) use the same shape — only the url changes. Point it at the server’s Runlayer proxy URL.

MCP Toolbox for Databases

The MCP Toolbox provides pre-built MCP servers for 40+ databases. Connect to one the same way, using its Runlayer proxy URL:

BigQuery
PostgreSQL

import asyncio
from google import genai
from google.genai import types

async def main():
    client = genai.Client(api_key="your-gemini-api-key")

    # Connect to MCP Toolbox BigQuery server
    mcp_config = types.LiveConnectConfig(
        mcp_servers=[
            {
                "url": "https://mcp.runlayer.com/toolbox-bigquery/mcp",
                "headers": {"Authorization": "Bearer your-token"}
            }
        ]
    )

    async with client.aio.live.connect(
        model="gemini-2.0-flash-exp",
        config=mcp_config
    ) as session:
        # Query your BigQuery data
        await session.send(
            "What are the top 10 products by revenue in the sales dataset?",
            end_of_turn=True
        )

        async for response in session.receive():
            if response.text:
                print(response.text)

asyncio.run(main())

from google import genai
from google.genai import types

async def query_postgres():
    client = genai.Client(api_key="your-gemini-api-key")

    mcp_config = types.LiveConnectConfig(
        mcp_servers=[
            {
                "url": "https://mcp.runlayer.com/toolbox-postgres/mcp",
                "headers": {"Authorization": "Bearer your-token"}
            }
        ]
    )

    async with client.aio.live.connect(
        model="gemini-2.0-flash-exp",
        config=mcp_config
    ) as session:
        await session.send(
            "Show me the schema for the users table",
            end_of_turn=True
        )

        async for response in session.receive():
            if response.text:
                print(response.text)

asyncio.run(query_postgres())

Show Supported databases (40+)

Google Cloud: BigQuery, AlloyDB, Spanner, Cloud SQL (PostgreSQL, MySQL, SQL Server), Firestore, Bigtable, Dataplex, Cloud MonitoringRelational: PostgreSQL, MySQL, SQL Server, SQLite, ClickHouse, TiDB, YugabyteDBNoSQL: MongoDB, Couchbase, Redis, Valkey, CassandraGraph: Neo4j, DgraphAnalytics: Looker, Trino

Multiple MCP Servers

Combine multiple MCP servers:

import asyncio
from google import genai
from google.genai import types

async def main():
    client = genai.Client(api_key="your-gemini-api-key")

    mcp_config = types.LiveConnectConfig(
        mcp_servers=[
            {
                "url": "https://mcp.runlayer.com/github-a1b2c3/mcp",
                "headers": {"Authorization": "Bearer github-token"}
            },
            {
                "url": "https://mcp.runlayer.com/toolbox-bigquery/mcp",
                "headers": {"Authorization": "Bearer bq-token"}
            }
        ]
    )

    async with client.aio.live.connect(
        model="gemini-2.0-flash-exp",
        config=mcp_config
    ) as session:
        await session.send(
            "Get the latest issues from our repo and cross-reference with usage data from BigQuery",
            end_of_turn=True
        )

        async for response in session.receive():
            if response.text:
                print(response.text)

asyncio.run(main())

​Copy Prompt

​Installation

​HTTP Transport (Production)

​Multiple MCP Servers

​Agent Accounts

​Resources

​Installation

​Connect

​Streaming Responses

​Multiple MCP Servers

​Next.js API Route

​Resources

​Installation

​Connect

​Tool Filtering

​Multiple MCP Servers

​Using MCP Prompts

​Resources

​Installation

​Connect to an MCP Server

​MCP Toolbox for Databases

​Multiple MCP Servers

​Resources

Copy Prompt

Installation

HTTP Transport (Production)

Multiple MCP Servers

Agent Accounts

Resources

Installation

Connect

Streaming Responses

Multiple MCP Servers

Next.js API Route

Resources

Installation

Connect

Tool Filtering

Multiple MCP Servers

Using MCP Prompts

Resources

Installation

Connect to an MCP Server

MCP Toolbox for Databases

Multiple MCP Servers

Resources