ua0leg / yii2-mcp
Yii2 MCP server module: Streamable HTTP endpoint, optional OAuth 2.1 for Claude connectors, and in-process tool runner
Requires
- php: >=8.2
- mcp/sdk: ^0.9.0
- nyholm/psr7: ^1.8
- symfony/psr-http-message-bridge: ^7.0
- yiisoft/yii2: ~2.0.45
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Yii2 extension that hosts a production MCP server for your app: Streamable HTTP via the official mcp/sdk, optional OAuth 2.1 for Claude connectors, and an in-process LocalMcpRunner for OpenAI-style tool calling.
This package does not ship framework introspection tools (schema/routes/logs). You add your own #[McpTool] classes. Treat /mcp like an admin API.
Requirements
- PHP 8.2+
- Yii2 ~2.0.45
Installation
Step 1 — Composer
composer require ua0leg/yii2-mcp
If not on Packagist yet, use VCS or a path repo:
{
"repositories": [
{
"type": "path",
"url": "../yii2-mcp",
"options": { "symlink": true }
}
],
"require": {
"ua0leg/yii2-mcp": "@dev"
}
}
Step 2 — Register the module
config/web.php:
'modules' => [ 'mcp' => [ 'class' => \Ua0leg\Yii2Mcp\Module::class, 'serverName' => 'MyApp MCP', 'serverVersion' => '1.0.0', 'publicUrl' => 'https://example.com', // required for OAuth discovery 'enableOauth' => true, // Claude remote connectors 'discoveryPath' => '@app', 'discoveryDirs' => ['mcp'], // finds app\mcp\* with #[McpTool] 'allowedHosts' => ['*'], 'allowedOrigins' => ['*'], 'userClass' => \app\models\User::class, 'loginFormClass' => \app\models\LoginForm::class, 'loginIdentityAttribute' => 'email', 'accessChecker' => static function ($user): bool { return (int) $user->role === \app\models\User::ROLE_ADMIN; }, 'toolClasses' => [ // optional: LocalMcpRunner \app\mcp\OrderTools::class, ], 'authorizeHeading' => 'Connect MyApp to Claude', 'authorizeHint' => 'Sign in with an admin account to authorize MCP access.', ], ],
| Option | Description | Default |
|---|---|---|
serverName / serverVersion |
Advertised in MCP initialize |
Yii2 MCP / 1.0.0 |
publicUrl |
Public HTTPS origin (no trailing slash) | '' (falls back to request host) |
enableOauth |
OAuth 2.1 AS for Claude connectors | false |
discoveryPath / discoveryDirs |
Where mcp/sdk discovers #[McpTool] |
@app / ['mcp'] |
allowedHosts / allowedOrigins |
Streamable HTTP middleware allowlists | ['*'] |
userClass |
Identity class (required) | — |
accessChecker |
fn(IdentityInterface): bool |
allow all |
loginFormClass |
Required when enableOauth |
— |
toolClasses |
Classes for LocalMcpRunner |
[] |
Step 3 — URL rules (manual)
Rules are not auto-registered. Merge into urlManager:
use Ua0leg\Yii2Mcp\Module; 'urlManager' => [ 'rules' => array_merge( Module::suggestedUrlRules('mcp', enableOauth: true), [ // your other rules… ], ), ],
Or copy explicitly:
'mcp' => 'mcp/mcp/index', // only when enableOauth = true '.well-known/oauth-protected-resource/mcp' => 'mcp/oauth/protected-resource', '.well-known/oauth-protected-resource' => 'mcp/oauth/protected-resource', '.well-known/oauth-authorization-server' => 'mcp/oauth/authorization-server', '.well-known/openid-configuration' => 'mcp/oauth/openid-configuration', 'oauth/register' => 'mcp/oauth/register', 'oauth/authorize' => 'mcp/oauth/authorize', 'oauth/token' => 'mcp/oauth/token',
Exempt the MCP/OAuth controllers from CSRF or session auth filters if your app applies them globally (Bearer / OAuth handle auth).
Step 4 — Add tools
<?php namespace app\mcp; use Mcp\Capability\Attribute\McpTool; class OrderTools { #[McpTool(name: 'search_orders', description: 'Search orders by query')] public function searchOrders(string $query, int $limit = 10): array { // … return []; } }
Point Claude (or any Streamable HTTP client) at https://example.com/mcp.
Auth
- With OAuth: Claude connector discovery + login at
/oauth/authorize - Without OAuth:
Authorization: Bearer <user.auth_key or access token>
LocalMcpRunner (in-app agents)
Same #[McpTool] methods without an HTTP round-trip (e.g. DeepSeek / OpenAI function calling inside Yii):
$runner = Yii::$app->getModule('mcp')->getLocalMcpRunner(); $tools = $runner->openAiTools(); $result = $runner->call('search_orders', ['query' => 'acme', 'limit' => 5]);
Or construct directly:
use Ua0leg\Yii2Mcp\components\LocalMcpRunner; $runner = new LocalMcpRunner([\app\mcp\OrderTools::class]);
Security notes
- MCP tools run application code. Restrict with
accessCheckerand preferenableOauthor short-lived Bearer tokens in production. - Tighten
allowedHosts/allowedOriginswhen not developing locally. - Set
publicUrlto the canonical HTTPS origin when using OAuth behind a proxy. - OAuth clients/codes/tokens default to
@runtime/mcp-oauth(file store). Sessions use@runtime/mcp-sessions.
Publishing (maintainers)
git init git add . git commit -m "Initial release" git branch -M main git remote add origin https://github.com/ua0leg/yii2-mcp.git git push -u origin main git tag v1.0.0 && git push origin v1.0.0
Submit the repo to Packagist.
License
MIT