Operation Invoker
Shared in-process HTTP-kernel transport for invoking v1 API operations from MCP, the Artisan CLI, and the API Explorer.
Overview
App\Services\Api\OperationInvoker executes a v1 API operation in-process through Laravel's full HTTP kernel. MCP meta-tools, curated tools, signals:api call, and the web API Explorer all share this transport so they mirror an external Sanctum client: the same middleware stack (auth, throttling, metering, idempotency, logging) and the same ability/permission checks.
It is not a registration registry — there is no register() catalogue. The invoker is a singleton-friendly service that turns a catalogue method/URI (plus auth credentials) into an OperationInvocationResult.
Public surface
| Method | Purpose |
|---|---|
invoke() |
Run one API call and return status, headers, decoded body, and duration |
Accepted invocation shape
$result = app(OperationInvoker::class)->invoke(
auth: $plainTextToken, // string|token|ExternalInvocationPrincipal
method: 'GET',
uri: '/api/v1/catalogue_items/{catalogue_item}',
pathParams: ['catalogue_item' => 42],
query: ['per_page' => 10],
body: [], // JSON-encoded for non-GET when non-empty
idempotencyKey: null, // optional Idempotency-Key header
headers: [], // Authorization is always overwritten
);
Auth credentials may be:
| Type | Behaviour |
|---|---|
| Plain-text bearer string | Used as-is |
NewAccessToken |
Uses its plain-text value |
PersonalAccessToken |
Installs the existing token and preserves its abilities and identity |
ExternalInvocationPrincipal |
Installs the resolved PAT, OAuth, stdio, CLI, or test principal. Abilities, connection generation, tenant, transport, and audit identity are preserved without storing a bearer secret |
User |
Direct in-process invocation only. External transports must resolve a token or connection principal first |
Result shape
OperationInvocationResult is a readonly value object:
| Property / method | Meaning |
|---|---|
status |
HTTP status code |
headers |
Multi-value response headers |
body |
Decoded JSON, raw string, or null when empty |
durationMs |
Wall-clock duration |
successful() |
true when status is 2xx |
json() |
Body when it is an array, otherwise null |
Body-bearing success responses contain data and optional root meta. The invoker returns that HTTP body unchanged; select data to read the resource or collection.
Consumers
App\Mcp\Tools\ExecuteEndpointand curated MCP tools (CuratedApiTool)App\Console\Commands\Api\SignalsApiCommand(callaction)App\Actions\Api\ExecuteExplorerRequest(API Console Explorer)
Worked example
$token = $user->createToken('cli', ['catalogue-items:read'])->plainTextToken;
$result = app(OperationInvoker::class)->invoke(
auth: $token,
method: 'GET',
uri: '/api/v1/catalogue_items',
query: ['per_page' => 5],
);
$result->successful(); // true on 2xx
$result->json()['data'] ?? [];
Missing abilities or gate permissions surface as ordinary HTTP 403 responses in the result — the invoker does not throw for API-level authorization failures.