laravel

This Laravel MCP server implements the Model Context Protocol (MCP) and exposes tools and resources via a standard JSON-RPC 2.0 interface. It supports multiple authentication methods (API keys, Basic Auth, Bearer tokens) and includes a robust permission system with field-level access control, plus per-key rate limiting and audit logging. After running the server container, clients can send JSON-RPC requests to discover, call, and manage tools and resources defined by your Laravel application. Typical use cases include prompting an AI agent to query product catalogs, status endpoints, or perform read/write operations within the app, all while respecting configured permissions and rate limits. The server auto-discovers tools and resources from your Laravel codebase and provides a consistent API surface for model-driven workflows.

Prerequisites:

• Docker installed on host
• Access to a container registry for the laravel MCP server image
• A Laravel application with the chaoticingenuity/laravel-mcp-server package installed or available via image

1. Pull and run the container

$ docker pull chaoticingenuity/laravel-mcp-server $ docker run -i --env-file .env -p 8080:80 chaoticingenuity/laravel-mcp-server

2. (Alternative) Build your own image from source

• Ensure PHP 8.1+ and Composer are available in the image
• Install the package: composer require chaoticingenuity/laravel-mcp-server
• Publish configuration and controllers as needed:

$ php artisan vendor:publish --tag=mcp-config $ php artisan vendor:publish --tag=mcp-controllers

3. Configure environment

• Create a .env with MCP settings (see section 4 of README for examples)
• Ensure SSL/HTTPS is enabled in production (MCP_REQUIRE_HTTPS=true)

4. Verify the server is running

• Access the MCP endpoint (e.g., http(s)://your-host/api/mcp) and test authentication and a sample RPC call
• Use artisan route:list and route:show to confirm MCP routes and middleware are loaded

5. Optional: Run tests

• $ vendor/bin/phpunit --testsuite mcp

Note: The container image and command may vary; adapt the docker run command to your hosting environment and image naming.

Tips and common issues:

• Ensure environment variables for server name, version, authentication, and security are correctly set in .env or docker environment.
• If you enable per-key rate limiting, monitor bursts to avoid false positives; tune MCP_RATE_LIMIT and MCP_BURST_LIMIT accordingly.
• For advanced permission resolution, implement custom resolvers by extending the provided interfaces and registering them in your Laravel service provider.
• If you publish mcp-config or mcp-controllers, keep a versioned backup so upgrades don’t overwrite custom changes.
• Use MCP_TRACK_PERMISSIONS to log permission checks for auditing purposes.
• When using API keys, rotate keys regularly and implement scope-based permissions to minimize risk.
• Enable MCP_LOG_REQUESTS and MCP_LOG_PERFORMANCE in production to facilitate debugging and monitoring.