Model Context Protocol (MCP)

​

What is MCP?

• Zero-Effort Tool Discovery (tools/list): Every documented route becomes an AI tool with strictly typed parameter schemas derived directly from your Form Requests, Data DTOs, and migrations.
• Autonomous Action Execution (tools/call): AI agents can execute real actions against your app. You can ask an agent: “Find user alex@example.com and update their role to admin”, and the agent will discover GET /api/users and dispatch PATCH /api/users/{id} on its own. Available through the stdio server; over HTTP it is opt-in.
• Isolated Authentication: Bearer tokens and API keys are injected at the HTTP layer and never exposed in the OpenAPI document or prompt context.

​

Running the Live MCP Server

php artisan geni:mcp:serve

• tools/list: Returns all available endpoints formatted as tool definitions.
• tools/call: Dispatches HTTP requests to your application and returns structured responses.

​

Connecting to Claude Desktop

{
  "mcpServers": {
    "my-laravel-api": {
      "command": "php",
      "args": [
        "/path/to/your/laravel/artisan",
        "geni:mcp:serve",
        "--base-url=http://localhost:8000"
      ]
    }
  }
}

​

Generating Static Manifests

# Export MCP tool manifest
php artisan geni:mcp --path=mcp-tools.json

# Export a client configuration snippet (mcpServers block)
php artisan geni:mcp --format=client-config --base-url=https://api.example.com

​

HTTP MCP Endpoint

• GET /docs/api/mcp: Returns tool definitions as JSON.
• POST /docs/api/mcp: Handles JSON-RPC 2.0 requests: initialize, ping, tools/list and, when enabled, tools/call.

​

Enabling HTTP Execution

GENI_MCP_HTTP_EXECUTION=true

'mcp' => [
    // ...
    'http_execution' => (bool) env('GENI_MCP_HTTP_EXECUTION', false),
],

​

Protocol Details

• JSON only: POST requests must be sent with Content-Type: application/json; anything else returns 415 Unsupported Media Type. This keeps cross-site forms and text/plain requests out.
• No CSRF: the MCP routes skip CSRF verification in every auth mode, so adding web to geni.middleware (or using form auth) does not break JSON-RPC clients.
• Notifications: JSON-RPC notifications (requests without an id, such as notifications/initialized) never receive a JSON-RPC response; the HTTP endpoint answers them with 204 No Content.
• Version negotiation: initialize answers with the protocol version the client requested when it is supported (2025-06-18, 2025-03-26 or 2024-11-05), and with 2025-06-18 otherwise.
• Errors: internal exceptions are reported to your application’s exception handler; clients only receive a generic Internal error.

​

Tool Naming

• snake (default): tools are named from the method and path (for example get_api_posts). An explicit operationId (@operationId or #[Endpoint(operationId: ...)]) is converted to snake case and used instead. The operationIds that Geni generates automatically since 3.0 do not rename tools in this mode, so existing tool names stay stable.
• operation_id: tools use the operation’s operationId, including generated ones. See Operation IDs.

​

Security & Authentication

'mcp' => [
    'enabled' => true,
    'http_execution' => (bool) env('GENI_MCP_HTTP_EXECUTION', false),
    'execution' => [
        'base_url' => env('GENI_MCP_BASE_URL', 'http://localhost:8000'),
        'timeout' => 15,
        'verify_ssl' => true,
        'auth' => [
            'default_bearer_token' => env('GENI_MCP_BEARER_TOKEN'),
            'default_api_key' => env('GENI_MCP_API_KEY'),
        ],
    ],
],