Prism Relay

https://github.com/prism-php/relay
Admin
A seamless integration between Prism and Model Context Protocol (MCP) servers that empowers your AI...
Tokens:46,894
Snippets:332
Trust Score:7.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Real-World Example: Laravel Command Using MCP Tools

Source: https://github.com/prism-php/relay/blob/main/README.md

A complete Laravel command that creates an interactive CLI. It uses Relay::tools('puppeteer') to give the agent web browsing capabilities, with a system prompt from a view and configured generation parameters.

```php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Prism\Relay\Facades\Relay;
use Prism\Prism\Enums\Provider;
use Prism\Prism\Prism;
use Prism\Prism\Text\PendingRequest;

use function Laravel\Prompts\note;
use function Laravel\Prompts\textarea;

class MCP extends Command
{
    protected $signature = 'prism:mcp';

    public function handle()
    {
        $response = $this->agent(textarea('Prompt'))->asText();

        note($response->text);
    }

    protected function agent(string $prompt): PendingRequest
    {
        return Prism::text()
            ->using(Provider::Anthropic, 'claude-3-7-sonnet-latest')
            ->withSystemPrompt(view('prompts.nova-v2'))
            ->withPrompt($prompt)
            ->withTools([
                ...Relay::tools('puppeteer'),
            ])
            ->usingTopP(1)
            ->withMaxSteps(99)
            ->withMaxTokens(8192);
    }
}
```

--------------------------------

### start(): void

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/stdio-transport.md

Starts the stdio process idempotently. Initializes the process, launches it, verifies it started, and sends the initial JSON-RPC initialize and notifications/initialized messages.

```APIDOC
## start(): void

### Description
Idempotent (no-op while the process is running). Otherwise initializes the process, launches it, verifies it started, and sends the initial JSON-RPC messages.

### Method
start

### Endpoint
start(): void

### Throws
- `TransportException`
```

--------------------------------

### Install Relay via Composer

Source: https://github.com/prism-php/relay/blob/main/README.md

Install the package using Composer.

```bash
composer require prism-php/relay
```

--------------------------------

### start(): void

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/stdio-transport.md

Launches the process and initializes the MCP connection. Throws ServerConfigurationException if configuration is invalid.

```APIDOC
## start(): void

### Description
Launches the process and initializes the MCP connection. Throws ServerConfigurationException if configuration is invalid.

### Method
start

### Endpoint
start()

### Parameters
None

### Response
#### Success Response
- **void** - No return value

#### Error Response
- **ServerConfigurationException** - Thrown if 'command' or 'env' is missing
```

--------------------------------

### Publish Relay Configuration

Source: https://github.com/prism-php/relay/blob/main/README.md

Publish the configuration file after installation.

```bash
php artisan vendor:publish --tag="relay-config"
```

--------------------------------

### start(): void

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-sse-transport.md

Starts the SSE stream by opening a long-lived GET request to the configured SSE endpoint. This method initializes the transport and begins receiving server-sent events.

```APIDOC
## start(): void

### Description
Starts the SSE stream by opening a long-lived GET request to the configured SSE endpoint.

### Method
start

### Signature
```php
public function start(): void
```

### Parameters
None

### Returns
void
```

--------------------------------

### make() usage example

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-builder.md

Creates a Relay for the 'github' server using a token from the user. The commented lines show the equivalent manual construction.

```php
use Prism\Relay\RelayFactory;

$relay = (new RelayFactory)->withToken($user->mcp_token)->make('github');

// Equivalent to:
// $relay = new Relay('github');
// $relay->withToken($user->mcp_token);
```

--------------------------------

### start() method signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-transport.md

Signature for the start() method. It performs an idempotent handshake: initializes the session, validates HTTP and JSON-RPC responses, sends the notifications/initialized notification, and sets started to true. Throws AuthorizationException on HTTP 401 and TransportException on other failures.

```php
public function start(): void
```

--------------------------------

### StdioTransport::start(): void

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/stdio-transport.md

Starts the local MCP server subprocess and prepares the input stream for communication.

```APIDOC
## StdioTransport::start(): void

### Description
Starts the local MCP server subprocess and prepares the input stream for communication.

### Method
start

### Parameters
None

### Returns
void
```

--------------------------------

### Basic Usage: Integrate MCP Tools with Prism

Source: https://github.com/prism-php/relay/blob/main/README.md

Shows how to add MCP tools (e.g., Puppeteer) to a Prism text request using Relay::tools(). The agent can then use the provided tools for tasks like web navigation and screenshots.

```php
use Prism\Prism\Prism;
use Prism\Relay\Facades\Relay;
use Prism\Prism\Enums\Provider;

$response = Prism::text()
    ->using(Provider::Anthropic, 'claude-3-7-sonnet-latest')
    ->withPrompt('Find information about Laravel on the web')
    ->withTools(Relay::tools('puppeteer'))
    ->asText();

return $response->text;
```

--------------------------------

### StdioTransport::command(): string

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/stdio-transport.md

Returns the command string used to start the subprocess.

```APIDOC
## StdioTransport::command(): string

### Description
Returns the command string used to start the subprocess.

### Method
command

### Parameters
None

### Returns
string - The command string.
```

--------------------------------

### make() method signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-factory.md

Signature of the make() method. It returns a configured (but not yet started) Relay instance with the transport already constructed. Throws ServerConfigurationException when $config is null and config('relay.servers.{name}') is not set.

```php
public function make(string $serverName, ?array $config = null): Relay
```

--------------------------------

### Combine tools from multiple MCP servers in a Prism agent

Source: https://github.com/prism-php/relay/blob/main/README.md

Use Relay::tools() to fetch tools from multiple MCP servers (e.g., 'github' and 'puppeteer') and spread them into the withTools() method of a Prism text request. This allows a single agent to access tools from different servers.

```php
use Prism\Prism\Prism;
use Prism\Relay\Facades\Relay;
use Prism\Prism\Enums\Provider;

$response = Prism::text()
    ->using(Provider::Anthropic, 'claude-3-7-sonnet-latest')
    ->withTools([
        ...Relay::tools('github'),
        ...Relay::tools('puppeteer')
    ])
    ->withPrompt('Find and take screenshots of Laravel repositories')
    ->asText();
```

--------------------------------

### HttpSseTransport usage example

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-sse-transport.md

Creates an HttpSseTransport with a URL, timeout, and custom headers, then starts the transport, sends a 'tools/call' request, and handles TransportException. The close() method is also invoked automatically on destruction. Note that only the 'api_key' config key is read; a runtime access_token is not consulted.

```php
use Prism\Relay\Transport\HttpSseTransport;
use Prism\Relay\Exceptions\TransportException;

$transport = new HttpSseTransport([
    'url' => 'https://mcp.example.com/sse',
    'timeout' => 30,
    'headers' => ['User-Agent' => 'prism-php-relay/1.0'],
]);

try {
    $transport->start();
    $result = $transport->sendRequest('tools/call', [
        'name' => 'search',
        'arguments' => (object) ['q' => 'relay'],
    ]);
    // $result: ['content' => [['type' => 'text', 'text' => '…']], …]
} catch (TransportException $e) {
    Log::error('SSE MCP failure: '.$e->getMessage());
} finally {
    $transport->close(); // also auto-invoked on destruction
}
```

--------------------------------

### Relay configuration for Stdio transport

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/stdio-transport.md

Example config array for Relay with the Stdio transport, specifying the command parts, timeout, and environment variables. The command array includes a nested array that gets JSON-encoded and escaped.

```php
return [
    'puppeteer' => [
        'transport' => \Prism\Relay\Enums\Transport::Stdio,
        'command' => ['npx', '-y', '@modelcontextprotocol/server-puppeteer', ['debug' => true]],
        'timeout' => 60,
        'env' => ['NODE_ENV' => 'production', 'MCP_SERVER_PORT' => '3001'],
    ],
];
```

--------------------------------

### HTTP transport configuration for GitHub MCP server

Source: https://github.com/prism-php/relay/blob/main/README.md

Configure an HTTP-based MCP server connection with URL, API key, timeout, transport type, and custom headers. The `api_key` is static and can be overridden by a runtime token passed via `withToken()`.

```php
'github' => [
    'url' => env('RELAY_GITHUB_SERVER_URL', 'http://localhost:8000/api'),
    'api_key' => env('RELAY_GITHUB_SERVER_API_KEY'),
    'timeout' => 30,
    'transport' => Transport::Http,
    'headers' => [
        'User-Agent' => 'prism-php-relay/1.0',
    ]
],
```

--------------------------------

### Custom WebSocketTransport implementation example

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/transport-contract.md

Shows how to implement the Transport interface for a custom MCP transport. Note there is no public registration hook; TransportFactory hard-codes the three built-in transports.

```php
use Prism\Relay\Transport\Transport;
use Prism\Relay\Exceptions\TransportException;

class WebSocketTransport implements Transport
{
    public function start(): void
    {
        // connect + MCP initialize handshake
    }

    public function sendRequest(string $method, array $params = []): array
    {
        // send JSON-RPC frame, return the result array
        return ['ok' => true];
    }

    public function close(): void
    {
        // teardown
    }
}
```

--------------------------------

### Creating Relay instances with config-driven and inline config

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay.md

Shows two ways to instantiate Relay: using a server name that must exist in config/relay.php, or providing an inline config that bypasses the config file entirely. The inline config example uses the Http transport with a custom URL and timeout.

```php
use Prism\Relay\Relay;

// Config-driven server (must exist in config/relay.php)
$relay = new Relay('puppeteer');

// Inline config entirely bypasses config/relay.php
$relay = new Relay('github', [
    'transport' => \Prism\Relay\Enums\Transport::Http,
    'url' => 'http://localhost:8001/api',
    'timeout' => 15,
]);
```

--------------------------------

### Example .env fragment for Relay server definitions

Source: https://github.com/prism-php/relay/blob/main/_autodocs/configuration.md

Environment variable fragment used by the README's server definitions. Overrides cache duration and GitHub server URL/API key; these are conventional env vars read only through config helpers, not directly by the library.

```dotenv
RELAY_TOOLS_CACHE_DURATION=30
RELAY_GITHUB_SERVER_URL=https://mcp.github.example.com/api
RELAY_GITHUB_SERVER_API_KEY=sk-...
```

--------------------------------

### Handle MCP errors with specific exception types

Source: https://github.com/prism-php/relay/blob/main/README.md

Wrap Relay::tools() calls in a try-catch block to handle specific exceptions: ServerConfigurationException for missing/invalid server settings, ToolDefinitionException for tool definition issues, AuthorizationException for HTTP 401 (token missing/expired/invalid), TransportException for communication errors, ToolCallException for tool call failures, and RelayException for any other MCP-related errors. Each catch block shows how to log or respond to the error.

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

try {
    $tools = Relay::tools('puppeteer');
    // Use the tools...
} catch (ServerConfigurationException $e) {
    // Handle configuration errors (missing server, invalid settings)
    Log::error('MCP Server configuration error: ' . $e->getMessage());
} catch (ToolDefinitionException $e) {
    // Handle issues with tool definitions from the MCP server
    Log::error('MCP Tool definition error: ' . $e->getMessage());
} catch (AuthorizationException $e) {
    // Handle HTTP 401 — token is missing, expired, or invalid
    return redirect('/oauth/reconnect');
} catch (TransportException $e) {
    // Handle communication errors with the MCP server
    Log::error('MCP Transport error: ' . $e->getMessage());
} catch (ToolCallException $e) {
    // Handle errors when calling a specific tool
    Log::error('MCP Tool call error: ' . $e->getMessage());
} catch (RelayException $e) {
    // Handle any other MCP-related errors
    Log::error('Relay general error: ' . $e->getMessage());
}
```

--------------------------------

### Define MCP Servers in config/relay.php

Source: https://github.com/prism-php/relay/blob/main/README.md

Configure MCP server connections with unique names and transport types (Stdio or Http). Includes cache_duration setting.

```php
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), // in minutes (0 to disable)
];
```

--------------------------------

### Create HTTP transport with TransportFactory

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/transport-factory.md

Example of creating an HttpTransport via TransportFactory::create() with a config array containing url, api_key, and timeout. The assert confirms the returned instance is HttpTransport.

```php
use Prism\Relay\Enums\Transport;
use Prism\Relay\Transport\TransportFactory;
use Prism\Relay\Transport\HttpTransport;

$config = [
    'url' => 'https://mcp.example.com/api',
    'api_key' => env('MCP_API_KEY'),
    'timeout' => 30,
];

$transport = TransportFactory::create(Transport::Http, $config);

assert($transport instanceof HttpTransport); // true
```

--------------------------------

### STDIO transport configuration for Puppeteer MCP server

Source: https://github.com/prism-php/relay/blob/main/README.md

Configure a locally running MCP server that communicates via standard I/O. The `command` array launches a subprocess; array values are passed as JSON encoded strings. Use the `env` option to pass environment variables to the server process for configuration, debugging, or authentication.

```php
'puppeteer' => [
    'command' => [
      'npx',
      '-y',
      '@modelcontextprotocol/server-puppeteer',
      '--options',
      // Array values are passed as JSON encoded strings
      [
        'debug' => env('MCP_PUPPETEER_DEBUG', false)
      ]
    ],
    'timeout' => 30,
    'transport' => Transport::Stdio,
    'env' => [
        'NODE_ENV' => 'production',  // Set Node environment
        'MCP_SERVER_PORT' => '3001',  // Set a custom port for the server
    ],
],
```

--------------------------------

### withToken

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-facade.md

Sets the token for the relay builder. This is forwarded through the facade's __callStatic method and matches the README example.

```APIDOC
## withToken

### Description
Sets the token for the relay builder. This is forwarded through the facade's __callStatic method.

### Method
Static method via __callStatic

### Signature
`withToken(string $token)`

### Parameters
- **token** (string) - Required - The token to use for authentication.

### Returns
`\Prism\Relay\RelayBuilder`
```

--------------------------------

### Direct StdioTransport usage with error handling

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/stdio-transport.md

Shows constructing StdioTransport, starting it, sending a request, and closing it. Catches ServerConfigurationException for missing config and TransportException for runtime failures. close() also runs via __destruct.

```php
use Prism\Relay\Transport\StdioTransport;
use Prism\Relay\Exceptions\ServerConfigurationException;
use Prism\Relay\Exceptions\TransportException;

try {
    $transport = new StdioTransport([
        'command' => ['npx', '-y', '@modelcontextprotocol/server-puppeteer'],
        'env' => ['DEBUG' => 'false'],
        'timeout' => 30,
    ]);
} catch (ServerConfigurationException $e) {
    // 'command'/'env' missing — configuration bug
    throw $e;
}

try {
    $transport->start();                      // launch + initialize
    $result = $transport->sendRequest('tools/call', [
        'name' => 'navigate',
        'arguments' => (object) ['url' => 'https://laravel.com'],
    ]);
} catch (TransportException $e) {
    Log::error('stdio MCP failure: '.$e->getMessage());
} finally {
    $transport->close();                      // also runs via __destruct
}
```

--------------------------------

### Runtime transport selection with Relay::tools()

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/transport-enum.md

Inline config example passing Transport::Http directly to Relay::tools() for runtime selection. Uses an API key from environment and a custom timeout.

```php
use Prism\Relay\Enums\Transport;
use Prism\Relay\Facades\Relay;

$tools = Relay::tools('github', [
    'transport' => Transport::Http,
    'url' => 'https://mcp.github.example.com/api',
    'api_key' => env('GITHUB_MCP_API_KEY'),
    'timeout' => 15,
]);
```

--------------------------------

### Token Flow with Error Handling

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-facade.md

Calls Relay::withToken() to get tools, catching ServerConfigurationException, AuthorizationException, and TransportException for specific error handling.

```php
use Prism\Relay\Facades\Relay;
use Prism\Relay\Exceptions\AuthorizationException;
use Prism\Relay\Exceptions\TransportException;
use Prism\Relay\Exceptions\ServerConfigurationException;

try {
    // Facade → RelayFactory::withToken() → RelayBuilder::tools()
    $tools = Relay::withToken($request->user()->mcp_token)->tools('github');
} catch (ServerConfigurationException $e) {
    // Stdio server + token, or unknown server
    Log::error('MCP config error: '.$e->getMessage());
} catch (AuthorizationException $e) {
    // Token rejected with HTTP 401
    return redirect('/oauth/reconnect');
} catch (TransportException $e) {
    // Non-401 transport failure
    Log::error('MCP transport error: '.$e->getMessage());
}
```

--------------------------------

### Handling AuthorizationException and TransportException

Source: https://github.com/prism-php/relay/blob/main/README.md

Catch `AuthorizationException` when the MCP server rejects the token with HTTP 401, indicating missing/expired/rejected token, and trigger re-authorization. Catch `TransportException` for other transport failures (non-401) and log the error.

```php
try {
    $tools = Relay::withToken($token)->tools('github');
} catch (AuthorizationException $e) {
    // Token is missing, expired, or rejected (HTTP 401)
    // Re-run the OAuth flow to get a fresh token
    return redirect('/oauth/reconnect');
} catch (TransportException $e) {
    // Other transport failure (non-401)
    Log::error('MCP Transport error: ' . $e->getMessage());
}
```

--------------------------------

### Passing OAuth Bearer token to Relay via Facade or instance

Source: https://github.com/prism-php/relay/blob/main/README.md

Attach a runtime Bearer token to requests for HTTP transport. The token takes priority over the static `api_key`. Use the Facade `Relay::withToken()` or a Relay instance. OAuth tokens are only supported with HTTP transport; using them with Stdio throws `ServerConfigurationException`.

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

// Via the Facade (returns a RelayBuilder)
$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();
```

--------------------------------

### Server configuration using Transport enum

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/transport-enum.md

Config file style example showing two servers: 'puppeteer' using Transport::Stdio with a command, and 'github' using Transport::Http with a URL. The 'transport' key accepts the enum cases directly.

```php
use Prism\Relay\Enums\Transport;
use Prism\Relay\Facades\Relay;

// Config file style
return [
    'servers' => [
        'puppeteer' => [
            'transport' => Transport::Stdio,
            'command' => ['npx', '-y', '@modelcontextprotocol/server-puppeteer'],
            'timeout' => 60,
            'env' => [],
        ],
        'github' => [
            'transport' => Transport::Http,
            'url' => env('RELAY_GITHUB_SERVER_URL', 'http://localhost:8001/api'),
            'timeout' => 30,
        ],
    ],
];
```

--------------------------------

### Direct HttpTransport usage with error handling

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-transport.md

Shows how to instantiate HttpTransport with URL, API key, and timeout, then start, send requests, and close. Catches AuthorizationException for HTTP 401 and TransportException for HTTP failures, invalid JSON-RPC, JSON-RPC errors, or timeouts.

```php
use Prism\Relay\Transport\HttpTransport;
use Prism\Relay\Exceptions\AuthorizationException;
use Prism\Relay\Exceptions\TransportException;

$transport = new HttpTransport([
    'url' => 'https://mcp.example.com/api',
    'api_key' => env('MCP_API_KEY'),
    'timeout' => 15,
]);

try {
    $transport->start();
    $toolsResult = $transport->sendRequest('tools/list');
    $result = $transport->sendRequest('tools/call', [
        'name' => 'my_tool',
        'arguments' => (object) ['query' => 'laravel'],
    ]);
} catch (AuthorizationException $e) {
    // HTTP 401 during initialize or request
} catch (TransportException $e) {
    // HTTP failure, invalid JSON-RPC, JSON-RPC error, timeout
} finally {
    $transport->close();
}
```

--------------------------------

### initialize JSON-RPC request with clientInfo

Source: https://github.com/prism-php/relay/blob/main/_autodocs/endpoints.md

Sent by HttpTransport::start(), StdioTransport::sendPingRequest(), and HttpSseTransport::performInitialize() during transport start(). Uses protocolVersion 2025-03-26 and clientInfo prism-relay/1.0.0; StdioTransport omits clientInfo and uses protocol 2024-11-05. HttpSseTransport validates the response for protocolVersion, while HttpTransport only validates the envelope.

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "prism-relay", "version": "1.0.0" }
  }
}
```

--------------------------------

### boot() method signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-service-provider.md

Signature for the boot() method that publishes the configuration file when running in the console.

```php
public function boot(): void
```

--------------------------------

### Publishing configuration in boot()

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-service-provider.md

Publishes the package's config/relay.php to the application's config directory with the 'relay-config' tag, only when running in the console.

```php
$this->publishes([
    __DIR__.'/../config/relay.php' => config_path('relay.php'),
], 'relay-config');
```

--------------------------------

### HttpTransport class declaration

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-transport.md

Declares the HttpTransport class implementing the Transport interface. It tracks a requestId, started flag, and optional sessionId. The constructor accepts a config array, and methods include start, sendRequest, and close.

```php
class HttpTransport implements Transport
{
    protected int $requestId = 0;
    protected bool $started = false;
    protected ?string $sessionId = null;

    public function __construct(array $config)

    public function start(): void

    public function sendRequest(string $method, array $params = []): array

    public function close(): void
}
```

--------------------------------

### tools(): array

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay.md

Fetches the MCP server's tool definitions and returns them as Prism Tool instances, ready to be passed to Prism::text()->withTools(...). Throws ToolDefinitionException on fetch failures and ServerConfigurationException if the constructor already threw.

```APIDOC
## [PHP] tools(): array

### Description
Fetches the MCP server's tool definitions and returns them as Prism `Tool` instances, ready to be passed to `Prism::text()->withTools(...)`.

### Method
`tools()`

### Endpoint
`public function tools(): array`

### Parameters
No parameters.

### Return
- **array<int, Tool>** - One `Prism\Prism\Tool` per valid tool definition (`name` + `description` present). Invalid definitions (missing `name` or `description`) are silently skipped (`isValidToolDefinition()`).

### Throws
- **ToolDefinitionException** - When fetching tool definitions from the server fails. The original error is wrapped: `"Failed to fetch tools from MCP server '{$serverName}': {$e->getMessage()}"` (previous exception set). Triggered by transport failures, JSON-RPC errors, timeout, HTTP 401 (`AuthorizationException` is the previous exception), etc., since `fetchToolDefinitions()` wraps any `\Throwable`.
- **ServerConfigurationException** - If the constructor already threw, or indirectly from transport construction.

### Caching
Tool definitions are cached in Laravel's default cache driver under the key built by `buildCacheKey()`:

```
relay-tools-definitions-{serverName}
relay-tools-definitions-{serverName}-{sha256(access_token)[:16]}   // when withToken() was used
```

The cache duration comes from `config('relay.cache_duration', 60)` minutes; the value `0` disables caching entirely (`Cache::has` / `Cache::put` are only called when the duration is `> 0`).

### Tool naming
Every generated tool is named `relay__{serverName}__{originalToolName}` (see `createBaseTool()`); for a server named `github` and MCP tool `create_issue` the Prism tool is `relay__github__create_issue`.

### Handler specialization
`createHandlerFunction()` inspects the tool's `inputSchema.properties` / `inputSchema.required` and picks one of six handler shapes (each handler ultimately calls `callMCPTool()` and returns a `string`):

| Condition | Handler signature | Payload sent to `tools/call` |
|---|---|---|
| Only required param is `url` | `fn ($url = null): string` | `['url' => $url]` |
| Only required param is `selector` | `fn ($selector = null): string` | `['selector' => $selector]` |
| Required params are exactly `selector` + `value` | `fn ($selector = null, $value = null): string` | `['selector' => …, 'value' => …]` |
| Any property named `name` | `fn ($name = null, $selector = null, $width = null, $height = null): string` | `['name' => …]` plus only the non-null optional `selector` / `width` / `height` |
| Any property named `script` | `fn ($script = null): string` | `['script' => $script]` |
| Default (generic) | `function (...$args): string` | Named (associative) args are forwarded as-is; a single array arg is used directly as params; otherwise positional args are mapped to the tools' `inputSchema.required` param names |

### Parameter schema mapping
`addParametersToTool()` maps each `inputSchema.properties` entry to a Prism `Schema` via `getSchemeParameter()` and registers it with `$tool->withParameter($parameter, $required)`:

| MCP `type` | Prism schema | Notes |
|---|---|---|
| `string` | `StringSchema` | |
| `number`, `integer` | `NumberSchema` | |
| `boolean` | `BooleanSchema` | |
| `enum` | `EnumSchema` | options read from `options` key |
| `object` | `ObjectSchema` | nested properties, `required` list, `allowAdditionalProperties` |
| `array` | `ArraySchema` | wraps the item schema (recursively resolved); `null` if item schema cannot be resolved |
| no `type` but `anyOf` present | `AnyOfSchema` | each `anyOf` branch resolved recursively |
| anything else | `null` (skipped) | e.g. `array` without resolvable items |

`getParameterDescription()` derives the description from the `description` property; for parameters named `url` it returns `'URL to navigate to'`; otherwise the fallback is `"Parameter {name} for {definitionName}"`.

### Tool call response formatting
Handlers return a string. `formatToolResponse()` handles two response shapes from `tools/call`:

- **`content` array** (`formatContentResponse()`): `text` items (with non-empty `text`) are joined with `"\n"`; `image` items (with `data`) render as `[Image data available]`. If the response has `isError` truthy, the result is prefixed with `ERROR: `. If both text and images are present, text wins; if content is empty the result is `Tool executed` / `Tool executed successfully`.
- **Other shapes** (`convertResponseToString()`): strings pass through; arrays/objects are `json_encode`d with `JSON_PRETTY_PRINT` (objects with `__toString` cast instead); scalars are cast to string; everything else yields `Tool executed successfully`.
```

--------------------------------

### Using getServerName with Relay instance

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay.md

Creates a Relay instance with server name 'github' and echoes the server name, outputting 'github'.

```php
$relay = new Relay('github');
echo $relay->getServerName(); // 'github'
```

--------------------------------

### close(): void

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-sse-transport.md

Closes the SSE stream and resets the session state. A subsequent start() establishes a brand-new session.

```APIDOC
## close(): void

### Description
Closes the SSE stream and resets the session state. A subsequent start() establishes a brand-new session.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **void** - No return value.

#### Response Example
N/A

### Errors
None documented.
```

--------------------------------

### Direct Instance Access (No Facade)

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-facade.md

Equivalent to using the facade but instantiates Relay directly via Relay::make() and calls tools() on the instance.

```php
$relay = Relay::make('puppeteer');     // \Prism\Relay\Relay
$tools = $relay->tools();
```

--------------------------------

### create() method signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/transport-factory.md

Public static method signature for create(), which accepts a Transport enum case and a server configuration array, returning a Transport instance.

```php
public static function create(TransportEnum $type, array $config): Transport
```

--------------------------------

### Transport interface definition

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/transport-contract.md

Defines the contract every MCP transport implements. Consumers like Relay only interact with this interface, calling start(), sendRequest(), and close().

```php
interface Transport
{
    public function start(): void;
    public function sendRequest(string $method, array $params = []): array;
    public function close(): void;
}
```

--------------------------------

### tools(string $serverName, ?array $config = null): array

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-builder.md

Shorthand for `$this->make($serverName, $config)->tools()`. Returns MCP tools as Prism tools with the token attached.

```APIDOC
## tools(string $serverName, ?array $config = null): array

### Description
Shorthand for `$this->make($serverName, $config)->tools()`. Returns MCP tools as Prism tools with the token attached.

### Method
tools

### Endpoint
RelayBuilder::tools

### Parameters
#### Path Parameters
- **$serverName** (string) - Required - MCP server name.

#### Query Parameters
- **$config** (?array) - Optional - Inline server config.

### Request Example
```php
use Prism\Prism\Prism;
use Prism\Relay\RelayFactory;
use Prism\Relay\Exceptions\AuthorizationException;
use Prism\Relay\Exceptions\TransportException;

$builder = (new RelayFactory)->withToken($request->user()->mcp_token);

try {
    $tools = $builder->tools('github');
    $response = Prism::text()
        ->using(\Prism\Prism\Enums\Provider::Anthropic, 'claude-3-7-sonnet-latest')
        ->withTools($tools)
        ->withPrompt('Open my latest pull request')
        ->asText();
} catch (AuthorizationException $e) {
    // HTTP 401 from the MCP server: token missing/expired/invalid.
    // ToolDefinitionException wraps the AuthorizationException; catch it directly
    // when calling through Relay::tools() with a \Throwable-aware handler, or
    // inspect the previous exception chain here.
    return redirect('/oauth/reconnect');
} catch (TransportException $e) {
    Log::error('MCP transport error: '.$e->getMessage());
}
```

### Response
#### Success Response (200)
- **array<int, Prism\Prism\Tool>** - The MCP tools as Prism tools, fetched with the token attached.

#### Response Example
```php
// Returns an array of Tool objects
```

### Errors
- **ServerConfigurationException** - Unknown server name or Stdio transport.
- **ToolDefinitionException** - Wraps AuthorizationException or TransportException when the server rejects the token while listing tools.
```

--------------------------------

### Construct and mutate a Prism Tool with as(), for(), using(), withParameter()

Source: https://github.com/prism-php/relay/blob/main/_autodocs/types.md

Shows how Relay constructs and mutates a Prism\Prism\Tool instance. The as() method sets the tool name (e.g., "relay__{server}__{tool}"), for() sets the description, using() sets the invocation handler, and withParameter() adds a parameter with required flag from inputSchema.required.

```php
use Prism\Prism\Tool;

// Construction & mutation as performed by Relay
$tool = new Tool;
$tool->as($toolName);                        // string  — sets the tool name ("relay__{server}__{tool}")
$tool->for($description);                    // string  — sets the description
$tool->using($handlerFunction);              // callable(string): string — sets the invocation handler
$tool->withParameter($parameter, $required); // Schema, bool — adds a parameter; $required from inputSchema.required
```

--------------------------------

### close method signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-transport.md

Declares the public method that closes the transport. Its body is a no-op because the transport holds no persistent resources beyond request state; the started flag is not reset here.

```php
public function close(): void
```

--------------------------------

### make

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-facade.md

Creates a new Relay instance for the given server name and optional configuration. This is a static method on the facade that delegates to the RelayFactory.

```APIDOC
## make

### Description
Creates a new Relay instance for the given server name and optional configuration.

### Method
Static method on the facade

### Signature
`make(string $serverName, array $config = null)`

### Parameters
- **serverName** (string) - Required - The name of the MCP server.
- **config** (array) - Optional - Configuration array for the server.

### Returns
`\Prism\Relay\Relay`
```

--------------------------------

### sendRequest(string $method, array $params = []): array

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-transport.md

Sends a JSON-RPC request over HTTP to the MCP server. It ensures the transport is started, increments the request ID, builds the payload, and processes the response.

```APIDOC
## sendRequest(string $method, array $params = []): array

### Description
Sends a JSON-RPC request over HTTP to the MCP server. It ensures the transport is started, increments the request ID, builds the payload, and processes the response.

### Method
POST

### Endpoint
(Not explicitly specified in source)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **$method** (string) - Required - JSON-RPC method (e.g., `tools/list`, `tools/call`).
- **$params** (array<string, mixed>) - Optional - JSON-RPC params; empty arrays are encoded as a JSON object (`\stdClass`).

### Request Example
```json
{ "jsonrpc": "2.0", "id": "2", "method": "tools/list", "params": {} }
```

### Response
#### Success Response (200)
- **result** (array<string, mixed>) - The JSON-RPC result, or `[]` when absent.

#### Response Example
(Not explicitly provided in source)

### Errors
- Re-throws `RelayException` subtypes as-is (`AuthorizationException`, `TransportException`).
- Wraps any other `\Throwable` in `TransportException` with message "Failed to send request to MCP server: …".
```

--------------------------------

### Example JSON-RPC request payload

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-transport.md

Shows the shape of the payload created by createRequestPayload(). Empty params are encoded as a JSON object (\stdClass) because some MCP HTTP servers require params to be an object, not an array.

```json
{ "jsonrpc": "2.0", "id": "2", "method": "tools/list", "params": {} }
```

--------------------------------

### tools(string $serverName, ?array $config = null): array

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-factory.md

Convenience one-liner that calls make() then ->tools() to convert MCP tools to Prism tools. Returns an array of Prism Tool objects.

```APIDOC
## tools(string $serverName, ?array $config = null): array

### Description
Convenience one-liner: calls `make()` then `->tools()`.

### Method
`tools`

### Signature
```php
public function tools(string $serverName, ?array $config = null): array  // @return array<int, Tool>
```

### Parameters
- **$serverName** (string) - Required - Server name as in `make()`.
- **$config** (?array, `array<string, mixed>`) - Optional - Default: `null` - Inline server configuration.

### Return
`array<int, Prism\Prism\Tool>` — the MCP tools converted to Prism tools.

### Throws
- `ServerConfigurationException`
- `ToolDefinitionException`

### Example
```php
use Prism\Prism\Prism;
use Prism\Relay\RelayFactory;

$factory = new RelayFactory;

$response = Prism::text()
    ->using(\Prism\Prism\Enums\Provider::Anthropic, 'claude-3-7-sonnet-latest')
    ->withTools($factory->tools('puppeteer'))
    ->withPrompt('Take a screenshot of prism-php/relay')
    ->asText();
```

### Error Handling Example
```php
use Prism\Relay\RelayFactory;
use Prism\Relay\Exceptions\ToolDefinitionException;
use Prism\Relay\Exceptions\ServerConfigurationException;

try {
    $tools = (new RelayFactory)->tools('github');
} catch (ServerConfigurationException $e) {
    Log::error('MCP server is not configured: '.$e->getMessage());
} catch (ToolDefinitionException $e) {
    Log::error('Could not list MCP tools: '.$e->getMessage(), ['previous' => $e->getPrevious()]);
}
```
```

--------------------------------

### tools(): array

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay.md

Fetches the MCP server's tool definitions and converts them into Prism Tool instances whose handlers call back into the MCP server.

```APIDOC
## tools(): array

### Description
Fetches the MCP server's tool definitions and converts them into Prism Tool instances whose handlers call back into the MCP server.

### Method
Method

### Signature
```php
public function tools(): array
```

### Return Value
- **array<int, Tool>** - An array of Prism Tool instances.
```

--------------------------------

### sendRequest method signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-transport.md

Declares the public method that sends a JSON-RPC request over HTTP. It calls start() if needed, increments requestId, POSTs the payload from createRequestPayload(), and processes the response. Throws RelayException subtypes as-is and wraps other Throwables in TransportException.

```php
public function sendRequest(string $method, array $params = []): array
```

--------------------------------

### tools(string $serverName, ?array $config = null): array

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-factory.md

Returns an array of Tool objects for the specified MCP server. Accepts the same configuration options as make().

```APIDOC
## tools(string $serverName, ?array $config = null): array

### Description
Returns an array of Tool objects for the specified MCP server. Accepts the same configuration options as make().

### Method
tools

### Signature
`public function tools(string $serverName, ?array $config = null): array`

### Parameters
- **$serverName** (string) - Required - MCP server name, used as the key into `config('relay.servers')` when `$config` is `null`.
- **$config** (?array) - Optional - Inline server configuration that bypasses the config file entirely.

### Return
array<int, Tool> - An array of Tool objects.

### Example
```php
// Example usage would be similar to make() but returns tools array.
```
```

--------------------------------

### Using RelayFactory::tools() with Prism text generation

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-factory.md

Creates a RelayFactory instance and passes the MCP tools from the 'puppeteer' server to Prism::text() for a prompt that takes a screenshot of prism-php/relay.

```php
use Prism\Prism\Prism;
use Prism\Relay\RelayFactory;

$factory = new RelayFactory;

$response = Prism::text()
    ->using(\Prism\Prism\Enums\Provider::Anthropic, 'claude-3-7-sonnet-latest')
    ->withTools($factory->tools('puppeteer'))
    ->withPrompt('Take a screenshot of prism-php/relay')
    ->asText();
```

--------------------------------

### Facade Usage with Prism

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-facade.md

Uses Relay::tools('github') to fetch MCP tools and pass them to Prism for a text generation request.

```php
use Prism\Relay\Facades\Relay;
use Prism\Prism\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::text()
    ->using(Provider::Anthropic, 'claude-3-7-sonnet-latest')
    ->withPrompt('Find my GitHub stars')
    ->withTools(Relay::tools('github'))
    ->asText();

return $response->text;
```

--------------------------------

### Using RelayFactory to create Relay instances

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-factory.md

Creates a RelayFactory instance and uses make() to obtain Relay instances. The first call resolves the server configuration from config('relay.servers') using the server name 'puppeteer'. The second call bypasses the config file by providing inline configuration for the 'github' server, including transport, URL, and timeout.

```php
use Prism\Relay\RelayFactory;

$factory = new RelayFactory;

// Config-file-resolved server
$relay = $factory->make('puppeteer');

// Inline config (bypasses config/relay.php)
$relay = $factory->make('github', [
    'transport' => \Prism\Relay\Enums\Transport::Http,
    'url' => 'https://mcp.example.com/api',
    'timeout' => 45,
]);
```

--------------------------------

### HttpSseTransport constructor signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/http-sse-transport.md

Constructor for HttpSseTransport that accepts a server configuration array. The config reads 'url' (SSE endpoint), 'timeout' (default 30), 'api_key', and 'headers'. Unlike StdioTransport, it does not perform eager config validation; failures surface at start().

```php
public function __construct(protected array $config)
```

--------------------------------

### Combine tokenized and regular tools in Prism agent

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-factory.md

Shows how to merge tools from a regular factory and a tokenized factory into a single Prism text request. The tokenized tools are created with withToken using the user's MCP token.

```php
use Prism\Prism\Prism;
use Prism\Relay\RelayFactory;

$factory = new RelayFactory;

$response = Prism::text()
    ->using(\Prism\Prism\Enums\Provider::Anthropic, 'claude-3-7-sonnet-latest')
    ->withTools([
        ...$factory->tools('puppeteer'),
        ...$factory->withToken($user->mcp_token)->tools('github'),
    ])
    ->withPrompt('Summarize my GitHub repos and screenshot the top one')
    ->asText();
```

--------------------------------

### notifications/initialized JSON-RPC notification

Source: https://github.com/prism-php/relay/blob/main/_autodocs/endpoints.md

Sent without an id and expecting no response. HttpTransport POSTs it during start() and validates the HTTP response, so 401/4xx/5xx still throws. HttpSseTransport POSTs it in sendInitializedNotification() and silently ignores failures. StdioTransport writes it to child stdin with no response expected.

```json
{ "jsonrpc": "2.0", "method": "notifications/initialized" }
```

--------------------------------

### register() method signature

Source: https://github.com/prism-php/relay/blob/main/_autodocs/api-reference/relay-service-provider.md

Signature for the register() method that merges package config and binds the relay factory.

```php
public function register(): void
```
Tokens:
Raw