Prism Relay

Define your MCP server connections in config/relay.php. Each server requires a unique name and specific configuration based on its transport type (Stdio or Http).

Key configuration options:

• command: (Stdio only) An array representing the command to execute.
• url: (Http only) The endpoint of the MCP server.
• api_key: (Http only) Static API key for authentication.
• timeout: Execution timeout in seconds.
• env: (Stdio only) Environment variables for the subprocess.
• transport: Use \Prism\Relay\Enums\Transport::Stdio or \Prism\Relay\Enums\Transport::Http.
• cache_duration: Tool cache duration in minutes (set to 0 to disable).

return [
    'servers' => [
        'puppeteer' => [
            'command' => ['npx', '-y', '@modelcontextprotocol/server-puppeteer'],
            'timeout' => 30,
            'env' => [],
            'transport' => \Prism\Relay\Enums\Transport::Stdio,
        ],
        'github' => [
            'url' => env('RELAY_GITHUB_SERVER_URL', 'http://localhost:8001/api'),
            'timeout' => 30,
            'transport' => \Prism\Relay\Enums\Transport::Http,
        ],
    ],
    'cache_duration' => env('RELAY_TOOLS_CACHE_DURATION', 60),
];

When you call tools(), Relay performs several transformations to make MCP tools compatible with the Prism ecosystem:

1. Naming: Tools are prefixed with relay__{serverName}__ to prevent collisions (e.g., relay__my_server__get_weather).
2. Parameter Mapping: MCP inputSchema properties are converted into Prism Schema objects (e.g., StringSchema, NumberSchema, EnumSchema, ObjectSchema, ArraySchema).
3. Handler Generation: A specialized handler function is generated for each tool. These handlers automatically map arguments to the correct MCP tool parameters.
4. Specialized Handlers: Relay detects common tool patterns to provide cleaner calling signatures:
   • URL-based: Tools requiring only a url parameter.
   • Selector-based: Tools requiring only a selector parameter.
   • Selector/Value-based: Tools requiring selector and value.
   • Name-based: Tools containing a name property in their schema.

To use dynamic OAuth tokens with HTTP transport, use the withToken() method. The runtime token takes priority over any static api_key defined in the configuration.

If the server returns an HTTP 401, Relay throws an AuthorizationException, which you should catch to trigger your application's re-authorization flow.

use Prism\Relay\Facades\Relay;
use Prism\Relay\Exceptions\AuthorizationException;
use Prism\Relay\Exceptions\TransportException;

try {
    // Via the Facade
    $tools = Relay::withToken($request->user()->mcp_token)->tools('github');
    
    // Or on a Relay instance
    $relay = Relay::make('github');
    $tools = $relay->withToken($request->user()->mcp_token)->tools();
} catch (AuthorizationException $e) {
    // Token is missing, expired, or rejected (HTTP 401)
    return redirect('/oauth/reconnect');
} catch (TransportException $e) {
    // Other transport failure (non-401)
    Log::error('MCP Transport error: ' . $e->getMessage());
}

The HttpTransport class is used to communicate with Model Context Protocol (MCP) servers over HTTP. It supports standard JSON-RPC 2.0 requests and handles both standard JSON responses and Server-Sent Events (SSE) for streamable HTTP.

When initializing the transport, you can provide a configuration array with the following keys:

• url (string): The base URL of the MCP server.
• access_token (string): An optional Bearer token for authentication. If provided, it takes precedence over api_key.
• api_key (string): An optional API key for authentication.
• headers (array): An associative array of additional HTTP headers to include in every request.
• timeout (int): The request timeout in seconds. Defaults to 30 if not specified.

$config = [
    'url' => 'https://mcp-server.example.com',
    'access_token' => 'your-bearer-token',
    'headers' => [
        'X-Custom-Header' => 'value',
    ],
    'timeout' => 60,
];

$transport = new \\Prism\\Relay\\Transport\\HttpTransport($config);

Relay uses specific exception types to allow for granular error handling:

• ServerConfigurationException: Configuration errors (e.g., missing server or invalid settings).
• ToolDefinitionException: Issues retrieving tool definitions from the MCP server.
• AuthorizationException: HTTP 401 errors (token missing, expired, or invalid).
• TransportException: Communication failures with the MCP server.
• ToolCallException: Errors occurring during the execution of a specific tool.
• RelayException: General MCP-related errors.

use Prism\Relay\Exceptions\ServerConfigurationException;
use Prism\Relay\Exceptions\ToolDefinitionException;
use Prism\Relay\Exceptions\AuthorizationException;
use Prism\Relay\Exceptions\TransportException;
use Prism\Relay\Exceptions\ToolCallException;
use Prism\Relay\Exceptions\RelayException;

try {
    $tools = Relay::tools('puppeteer');
} catch (ServerConfigurationException $e) {
    Log::error('MCP Server configuration error: ' . $e->getMessage());
} catch (ToolDefinitionException $e) {
    Log::error('MCP Tool definition error: ' . $e->getMessage());
} catch (AuthorizationException $e) {
    return redirect('/oauth/reconnect');
} catch (TransportException $e) {
    Log::error('MCP Transport error: ' . $e->getMessage());
} catch (ToolCallException $e) {
    Log::error('MCP Tool call error: ' . $e->getMessage());
} catch (RelayException $e) {
    Log::error('Relay general error: ' . $e->getMessage());
}