Current SqueHub versionv2.0.0
API and integration · v2.x

MCP capabilities, resources, and tools

The optional SqueHub Agent serves bounded metadata for one Application over local MCP STDIO. This page is the practical inventory for host operators. Use local MCP client setup to connect and the Agent and AI overview for architecture…

The optional SqueHub Agent serves bounded metadata for one Application over local MCP STDIO. This page is the practical inventory for host operators. Use local MCP client setup to connect and the Agent and AI overview for architecture, security, and Change Plan context. The framework reports version 2.0.0, and its served STDIO protocol revision is 2025-11-25.

Capability grants

The shipped Config/Agent.php returns ['grants' => []]. That permits six bounded reads and no plan creation or schema inspection. php squehub agent:status --json reports allowed, supported, risk, mode, scope, and scope_values for every named capability without displaying secrets.

CapabilityRiskModeDefaultSupported?ScopePurpose
read_framework_metadatalowreadAllowedYesNoneFramework identity, public Plugins symbols, and registered CLI inventory.
read_application_contractlowreadAllowedYesNoneBounded route-derived operation flags and selected application metadata.
read_routeslowreadAllowedYesNoneAlready registered routes or an existing validated route cache.
read_package_metadatalowreadAllowedYesNoneBounded Package and Kit activation metadata.
read_docslowreadAllowedYesNoneSearch physical Markdown under Documentation/.
read_health_metadatalowreadAllowedYesNoneAggregate, non-probing Health and infrastructure summaries.
read_schemasensitivereadDeniedYesconnectionsExact allowlisted connection metadata and table/index inspection.
read_sourcesensitivereadDeniedNorootsReserved source-inspection capability; no source tool is implemented.
read_logssensitivereadDeniedNosourcesReserved log-inspection capability; no log tool is implemented.
run_testsexecutionexecuteDeniedNosuitesReserved test-execution capability; no test-running tool is implemented.
create_planreviewreadDeniedYesoperationsExact allowlisted review-only Change Plan operations.
apply_planmutationwriteDeniedNofingerprintsReserved plan-application capability; MCP cannot apply plans.
run_migrationmutationwriteDeniedNoconnectionsReserved migration-execution capability; MCP cannot run migrations.
manage_packagemutationwriteDeniedNopackagesReserved Package-lifecycle capability; MCP cannot manage Packages.

The risk, mode, and scope columns are registry descriptors. Unsupported entries remain visible in status with allowed: false; Config/Agent.php cannot grant them. A scope name identifies the required allowlist key for a supported capability, not a permission by itself.

To deny a default read or grant only supported narrow scopes, edit the trusted local configuration and restart the MCP process:

PHP
return [
    'grants' => [
        'read_docs' => false,
        'read_schema' => ['connections' => ['reporting']],
        'create_plan' => ['operations' => ['migration_source', 'feature_blueprint']],
    ],
];

read_schema requires an exact connection name from the current application's database configuration. create_plan requires exact operation names. Unknown capabilities, an unscoped sensitive grant, and a grant for unsupported read_source, read_logs, run_tests, apply_plan, run_migration, or manage_package fail validation. Naming an operation in a prompt or tool argument does not grant it. The grants belong to the current Application root, so another application's MCP process has a separate inventory.

Resources

Resource discovery includes only permitted entries. Each resource uses application/json content. A client may read an available URI, but each read checks its capability again.

URIRequired capabilityReturned boundary
squehub://frameworkread_framework_metadataFramework version, served protocol, Application fingerprint, path-first routing example, bounded public Plugins symbols, and CLI inventory.
squehub://application/contractread_application_contractRoute-derived operation flags plus API version strategy and selected frontend/deployment metadata. It is not a full Contract or OpenAPI export. Denied read_routes produces state: denied with no operations.
squehub://routesread_routesAt most 100 route metadata records from already loaded registration or a validated existing route cache. Fresh uncached boot can be partial.
squehub://packagesread_package_metadataBounded Package/Kit activation and dependency metadata. No lifecycle execution.
squehub://healthread_health_metadataAggregate Health, infrastructure, Queue, and Scheduler states and counts. Connection and task labels are omitted. It is a snapshot, not a live end-to-end proof.
squehub://cliread_framework_metadataBounded names/descriptions from the registered CLI. Directly constructed Agent managers without that registry return unavailable.
squehub://schemaread_schema for a connectionNames and driver types from up to the first 32 configured connections, filtered by the exact allowlist; no credentials or records. Hidden without a scoped grant.

An allowed routes resource can report observed or partial; denying read_routes removes that URI from discovery and denies direct reads. The separate application contract projection then reports state: denied and no operations. Neither resource executes Project route PHP to complete an inventory. Other resources may report unavailable, configured, registered, or a truncated flag according to the source. Treat partial and unavailable as explicit limits, not a reason to request arbitrary files through the model.

Tools

Tool discovery is capability-filtered, and every call is checked again. The MCP SDK marks these tools as read-only and non-destructive. Unknown argument fields fail validation.

ToolRequired capabilityArgumentsResult
search_docsread_docsRequired query of 2–120 bytes; optional limit of 1–20, default 5.state, items with application-relative path, line, and bounded excerpt, plus truncated.
inspect_schemaread_schema for selected connectionRequired simple table identifier; optional exact connection name (otherwise configured default).Table existence and up to 64 index metadata entries; records_exposed: false.
create_plancreate_plan for selected operationRequired operation; target required except for migration_source.Subsystem Change Plan, fingerprint, provenance, applied: false, apply_supported: false.

search_docs reads only physical Markdown under this application's Documentation/ directory. It inspects at most 512 files of at most 256 KiB each and returns at most a 240-byte excerpt per match. This public guide tree is separate from local, untracked development records in Docs/; do not put secrets in either tree. An omitted installed documentation directory yields state: unavailable. The tool does not traverse arbitrary application files, links, vendor, or .env. inspect_schema calls the existing Schema reader for an allowlisted connection; it may access that database's metadata, but never returns table rows.

Review-only Change Plans

create_plan supports exactly four operations:

OperationTargetPlanner
migration_sourceOmit targetReviews Migration source candidates without executing their PHP or a database migration.
package_enableExisting Package nameAsks the Package planner for an enable plan.
kit_enableExisting Kit nameAsks the Kit planner for an enable plan.
feature_blueprintBounded feature nameAsks the Feature Blueprint generator for a multi-file plan.

For example, after granting only feature_blueprint, a host may call create_plan with:

JSON
{"operation":"feature_blueprint","target":"Post"}

The result contains a plan with operation, target, owner, actions, warnings, conflicts, preconditions, and Agent metadata; a plan fingerprint; and provenance with the framework version, Application fingerprint, creation time, and requested capability. Its applied and apply_supported fields are both false. The returned ChangePlan is review data with no private prepared execution handle. Review the exact actions and current state in the owning SqueHub Change Plan workflow. A plan fingerprint is an identity for review, not approval or an MCP execution permit; the owning subsystem retains authorization and freshness checks.

Security and transport limits

  • SqueHub MCP is local STDIO only. This connection exposes no remote HTTP transport, generic MCP apply_plan, arbitrary shell, network request, or general file read/write tool. The host may have separate tools with their own permissions.
  • Default resources omit .env, APP_KEY, token values, logs, private Storage, database rows, and arbitrary source. Keep secrets out of application-authored documentation and route descriptions that an AI host may summarize.
  • A 256 KiB input-line limit and a 64 KiB result limit bound STDIO messages. Resource lists, route metadata, Package details, docs hits, and schema indexes have additional limits; oversized results fail safely.
  • The optional SDK is experimental and installed only when MCP is enabled. The server advertises the protocol revision it actually serves, even if the SDK supports newer revisions.
  • The Agent uses inspection-only Package boot and does not run Package providers, Kit hooks, route source PHP, migrations, Seeders, Queue workers, or Scheduler tasks while inspecting. Normal application Config PHP still evaluates during bootstrap.

For a complete route or API contract export, use the deliberate route and Application Contract workflows outside Agent inspection. For connection and client errors, see MCP troubleshooting. The v2 release boundary is in SqueHub Status.