Search by

ua0leg / yii2-mcp

ua0leg

Yii2 MCP server module: Streamable HTTP endpoint, optional OAuth 2.1 for Claude connectors, and in-process tool runner

Package info

github.com/ua0leg/yii2-mcp

Type:yii2-extension

pkg:composer/ua0leg/yii2-mcp

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-19 20:35 UTC

This package is auto-updated.

Last update: 2026-11-19 20:43:13 UTC


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 accessChecker and prefer enableOauth or short-lived Bearer tokens in production.
  • Tighten allowedHosts / allowedOrigins when not developing locally.
  • Set publicUrl to 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