> ## Documentation Index
> Fetch the complete documentation index at: https://geni.masiting.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Turn your Laravel API into tools for AI agents like Claude Desktop, Cursor, and Claude Code.

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that allows AI assistants (such as Claude Desktop, Cursor, and Claude Code) to securely discover and invoke tools in external applications.

Geni turns your Laravel application into a fully autonomous, AI-ready toolkit:

* **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](mailto: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.
* **Isolated Authentication**: Bearer tokens and API keys are injected at the HTTP layer and never exposed in the OpenAPI document or prompt context.

<CardGroup cols={2}>
  <Card title="Live Stdio Server" icon="terminal">
    Run `php artisan geni:mcp:serve` for local AI clients like Claude Desktop or Claude Code.
  </Card>

  <Card title="HTTP Remote Endpoint" icon="globe">
    Access `GET` / `POST` on `/docs/api/mcp` for cloud AI agents and webhooks.
  </Card>
</CardGroup>

## Running the Live MCP Server

Geni includes a built-in stdio MCP server command:

```bash theme={null}
php artisan geni:mcp:serve
```

This starts a JSON-RPC server listening on standard input and output, responding to MCP protocol messages:

* `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

Add Geni to your `claude_desktop_config.json`:

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

Restart Claude Desktop, and your AI assistant can now search, inspect, and call your Laravel API endpoints directly!

## Generating Static Manifests

You can also export an MCP tool manifest or client configuration to a file:

```bash theme={null}
# Export MCP tool manifest
php artisan geni:mcp --path=mcp-tools.json

# Export Claude Desktop configuration snippet
php artisan geni:mcp --format=claude-desktop
```

## HTTP MCP Endpoint

Geni also serves an HTTP MCP discovery endpoint at `/docs/api/mcp`:

* `GET /docs/api/mcp`: Returns tool definitions as JSON.
* `POST /docs/api/mcp`: Executes tools calls via HTTP JSON-RPC.

This route inherits any authentication configured for your documentation portal.

## Security & Authentication

Configure token injection in `config/geni.php`:

```php config/geni.php theme={null}
'mcp' => [
    'enabled' => true,
    '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'),
        ],
    ],
],
```

<Warning>
  Authentication credentials configured in `execution.auth` are injected into HTTP requests during tool execution and are never leaked in tool schemas or manifest exports.
</Warning>