Sdk Laravel Package

Product Decisions This Supports

• AI Integration Roadmap: Still the core value — expose Laravel/PHP services as MCP tools/resources to LLM agents (Claude, Codex, internal copilots). v0.9.0 doesn't change the roadmap case, but it materially raises the maturity bar: concurrent sessions, elicitation/sampling, and streaming now behave correctly, which is what real agent workflows depend on.
• Build vs. Buy (shifted further toward Buy): The protocol layer is no longer "just JSON-RPC plumbing." This release fixes per-session concurrency, fiber resumption, response routing, and request/response correlation over Streamable HTTP — subtle distributed-systems bugs a product team should not be re-implementing. Buy the SDK; build only your domain tools and authorization policy.
• Architecture Decisions:
  • Authorization is now a resource-server-only concern (ADR 0002). The SDK no longer proxies OAuth, registers clients, or performs OIDC discovery on your behalf (OAuthProxyMiddleware, ClientRegistrationMiddleware, ClientRegistrarInterface, JwksProvider, OIDC metadata policies are removed). Decision: pick an external IdP (Auth0, Authentik, Keycloak, Cognito) and treat the MCP server as a protected resource. Budget for this — it's an integration, not a config toggle.
  • Multi-worker / multi-node deployment is now a first-class decision: opt-in Builder::setSessionLock() with FileSessionLock (single host) or SymfonyLockSessionLock (shared store, e.g. Redis). If you run Laravel Octane, Horizon workers, or multiple pods, you must plan a shared lock + session store or accept 503s under contention.
  • Protocol era transition: the SDK now serves both the handshake era and 2026-07-28 over stdio and HTTP. Plan a client-compatibility matrix rather than assuming one protocol revision.
  • Decoupling still holds: MCP server as sidecar/middleware, isolated from core business logic.
• Upgrade / Lifecycle Cost (new decision): v0.9.0 is a BC-breaking minor release on a 0.x line. Request IDs to clients are now UUIDs, TransportInterface::send() semantics changed, AccessToken is threaded through processInput()/handleMessage()/onMessage(), JwtTokenValidator is final with a single issuer, and requireScopes() is replaced by ScopePolicy. Decision: pin the SDK version, schedule a migration spike before any production commitment, and assume another BC break before 1.0.
• Security Posture as a Product Feature: ScopePolicy (per-method/per-tool 403 insufficient_scope with hierarchies), https-enforced ProtectedResourceMetadata, always-on Host validation with explicit allowedOrigins, and CORS preflight no longer 401-ing behind auth. This is sellable to security review boards — previously a blocker for enterprise deals.
• Use Cases (unchanged, now better supported):
  • Internal developer tools (CLI/API/DB exposed as MCP tools).
  • Customer-facing AI agents calling backend PHP services.
  • Microservices orchestration / tool federation across services.
  • Legacy modernization — wrapping monoliths as MCP servers.
• Monetization (unchanged): MCP-exposed tools as premium services; framework integrations as developer products. Note the resource-server narrowing means you are not shipping an auth product — partner with an IdP rather than reselling identity.

When to Consider This Package

Adopt MCP/PHP SDK When:

• Your PHP app must be callable by AI agents as tools/resources without building a protocol layer.
• You need hardened concurrency: multiple in-flight requests per session, elicitation/sampling round-trips, progress tokens, and streamed responses that don't cross wires. Pre-0.9.0 this was genuinely unsafe; now it's a reason to adopt.
• You're deploying stateless or horizontally scaled HTTP (Streamable HTTP + SSE, shared session store + SymfonyLockSessionLock).
• You already have (or will buy) an OAuth/OIDC identity provider and want the SDK to validate tokens and enforce scopes, not issue them.
• You need dual protocol-era support (handshake era + 2026-07-28) for heterogeneous agent clients.
• You value standards conformance (RFC 9728 metadata paths, SEP-2243 header validation, -32020/-32022 error codes) over a bespoke HTTP API.
• You can absorb 0.x churn: pinned versions, a migration budget, and a team comfortable reading changelogs with [BC Break] tags.

Look Elsewhere When:

• You need the SDK to be an OAuth authorization server, handle dynamic client registration, or do OIDC discovery for downstream clients. That was removed by design. Use a dedicated IdP.
• You require API stability / long-term support: this is a 0.x line shipping breaking changes in minor releases. If you can't pin and plan upgrades, wait for 1.0 or wrap it behind your own internal interface.
• Your AI use case is simple (static prompt → LLM → static response). A REST endpoint or a direct LLM SDK is cheaper.
• You're Python/JS-first: use LangChain/AutoGen and call PHP over plain HTTP.
• You're locked into a proprietary AI ecosystem with no MCP support.
• Latency budget is extremely tight: MCP still adds framing overhead; gRPC/WebSockets remain better for high-frequency internal calls.
• You cannot provide a shared lock/session backend for multi-worker deployments — you'll hit SessionLockTimeoutException → 503 under concurrent same-session load.
• Your team lacks both PHP depth and AI-agent protocol familiarity — the BC-break surface makes this costlier than it looks.

How to Pitch It (Stakeholders)

For Executives:

"The MCP PHP SDK lets us expose our existing PHP/Laravel backend to AI agents without a rewrite. v0.9.0 is the release that makes it production-credible: it fixes concurrent sessions, streaming, and response routing under real load, and it tightens security to an enterprise-acceptable posture — scoped authorization, strict host/origin validation, standards-compliant protected-resource metadata.

What that means commercially:

• Faster path to AI features — "summarize this record," "generate this report," "run this workflow" become tool calls against code we already own.
• Security review becomes passable — we delegate identity to a standard IdP and enforce per-tool scopes; the SDK no longer tries to be an auth server.
• New revenue surface — package internal tools as AI-callable services.
• The cost line — this is a 0.x library with breaking changes between minor versions. We pin the version and budget one migration sprint per upgrade cycle before 1.0. That's the trade for not building a protocol stack ourselves.**

Bottom line: buy the protocol, build the tools, rent the identity."

For Engineers:

"v0.9.0 is a hardening release with real BC breaks — read the migration list before upgrading.

Wins:

• Concurrency is fixed properly: per-session opt-in lock (Builder::setSessionLock(); FileSessionLock for single-host, SymfonyLockSessionLock for shared/Redis), partial Session::save() so parallel requests stop clobbering each other, UUID request IDs so parallel elicitations/progress tokens can't cross, and correct fiber resumption on stdio.
• Fail-fast client: no more waiting out timeouts; unreachable Psr16SessionStore returns 503 (retryable) instead of a misleading 404.
• Security narrowed and strengthened: resource-server-only authorization (ADR 0002), ScopePolicy as the third AuthorizationMiddleware arg with scope hierarchies, https-enforced ProtectedResourceMetadata, DnsRebindingProtectionMiddleware always validating Host plus separate allowedOrigins, and CORS preflight no longer 401-ing. PassthroughMiddleware lets you opt out of the default stack explicitly.
• Protocol eras: stdio and HTTP serve both the handshake era and 2026-07-28; StatelessAwareTransportInterface::setHandshakeVersions() declares what you negotiate.

Migration checklist (all [BC Break]):

1. Client-directed request IDs are Uuid — update sendRequest(), checkResponse(), handleFiberYield(), and transport response finders.
2. TransportInterface::send() now receives every response of a non-suspending handler; the outgoing queue only carries server-initiated requests/notifications. Custom transports must deliver each message (a batch yields several).
3. AccessToken is threaded through processInput(), handleMessage(), handlePostRequest(), and the onMessage() listener (4th arg). Replace OAuthRequestMetaMiddleware with RequestContext::getAccessToken(); AuthorizationResult::allow() takes an AccessToken.
4. JwtTokenValidator is final, single-issuer, takes a key set (CachedKeySet); fromIssuer() caches in PSR-6 and refetches on unknown kid. requireScopes() → ScopePolicy. alg allowlist enforced.
5. Remove any use of OAuthProxyMiddleware, ClientRegistrationMiddleware, ClientRegistrarInterface, JwksProvider*, OidcDiscoveryInterface — move that to your IdP.
6. DnsRebindingProtectionMiddleware signature changed; allowedOrigins is the new second arg and defaults to empty.
7. ProtectedResourceMetadata requires $resource, derives its path (RFC 9728 §3.1), and requires https except loopback.

Pinning guidance: treat the SDK as an internal dependency — wrap it behind our own tool-registration interface so the next [BC Break] is a localized change, not a codebase-wide sweep."

For Developers:

"The DX is unchanged at the happy path — the complexity moved into correctness and security.

#[McpTool]
public function generateReport(User $user): string { ... }

What you get under the hood in 0.9.0:

• Server: attribute/manual discovery, now safe under concurrent same-session requests; opt into a session lock when you scale beyond one worker.
• Client: fails fast instead of hanging; UUID-correlated requests so parallel elicitation/sampling answers land on the right call.
• Transports: STDIO and Streamable HTTP (SSE for queued messages, 202 for response/notification-only POSTs), both speaking the handshake era and 2026-07-28.
• Auth: you receive a validated AccessToken and enforce scopes with ScopePolicy; the SDK no longer proxies OAuth or registers clients — point it at your IdP's JWKS.

Practical advice: pin the version, run the migration checklist from the changelog, and keep tool handlers thin so the next BC break is a one-file fix. Perfect for CLI tools, APIs, and legacy classes you want to expose to agents — just don't expect 1.0 stability yet."