Internal agent surface

MCP Toolkit — Reality, Dream, Bridge

MCP problems are usually scope problems before they are tool problems.

/doctor MCP issues can come from several layers at once: project declarations, host-global configuration, plugin caches, proxy transport, browser permissions, or stale authentication. Agents may inspect, explain, and classify. Humans own host-global remediation.

Boundary

Do not edit host-global MCP config, auth caches, plugin files, or Stackmates configuration from this page. Use this as the operating model, not a cleanup script.

Reality

Separate the layers before diagnosing the issue.

A noisy MCP report is rarely a single list of broken tools. It is a stack of declarations, host-visible connectors, runtime permissions, and cached state.

confirmed current project layer

Project-declared MCPs

The Stackmates project declaration is narrow. Its .mcp.json currently declares two servers.

perplexity-askstackmates-cli

visible to sessions, not project-owned

Host-global and plugin MCPs

Claude, plugins, browser helpers, and cached host surfaces can expose many more connectors to Stackmates sessions than the project declaration names.

GitHubContext7Chrome/browserVercelGoogle Workspace

often the source of noisy doctor findings

Runtime transport and permission layer

A connector can be conceptually useful and still fail today because its transport, proxy, browser tab, or auth state is stale.

proxy 502connection timeoutneeds-authbrowser permission denied

/doctor categories

Explain the category without taking ownership of the host.

These categories describe observed MCP failure modes. They do not prove a connector is part of the project contract, and they do not authorize agent-side remediation.

cached needs-auth

A host cache still thinks a connector needs authentication, even if the current task does not need it.

Report the connector and owner. Do not refresh credentials or write auth files.

proxy 502s

The request path is failing between client, proxy, and MCP process.

Treat as transport evidence. Prefer a cheaper CLI path if the job can still be done.

connection timeouts

The server did not respond inside the client window, often because the process failed to start or is waiting on auth.

Classify as defer or auth until a human operator confirms the server is commissioned.

browser or tab permission failures

A browser MCP cannot access the required page, tab, profile, or permission scope.

Ask for explicit human setup only when browser inspection is necessary.

stale plugins

Installed plugin definitions can outlive the workflow that originally needed them.

Name the stale surface and recommend disable review. Do not mutate plugin files.

token and security overhead

Excess tools enlarge the prompt surface and permission boundary before they create value.

Prefer the smallest sufficient toolset and mark unused connectors for disable review.

Dream

A lean commissioned toolkit, not a novelty shelf.

Every connector earns its place by job, scope, proof, and human ownership. A connector without an owner is not commissioned.

Named job

What work does this connector do that no cheaper path does well?

Trust level

Is it read-only, write-capable, spend-capable, or identity-bearing?

Auth owner

Which human owns credentials, renewal, and revocation?

Read/write scope

Which repos, accounts, databases, tabs, or documents may it touch?

Proof

What evidence shows the connector works and earns its token cost?

Kill switch

How does a human disable it quickly without breaking unrelated work?

Review cadence

When does it get re-justified, re-authenticated, or removed?

Bridge

Use the Dreamineering method.

Move from inventory to desired model to classification. Keep the human/operator boundary explicit.

Reality

Inventory what exists without mutating any host-global files.

Proof: Project declarations, visible session tools, observed doctor categories, and current task demand.

Dream

Define the desired scoped toolkit by job, not novelty.

Proof: Each connector has job, trust level, owner, scope, proof, kill switch, and review cadence.

Bridge

Classify every visible connector as keep, auth, defer, disable, or replace with CLI.

Proof: A short classification list that explains why each connector earns or loses its place.

Human remediation

Hand host-global cleanup to a human/operator.

Proof: No agent writes to host config, auth caches, plugin files, or Stackmates MCP configuration.

Classification language

keep

Commissioned, working, scoped, and materially better than the CLI path.

auth

Useful, but blocked on human-owned credentials or consent.

defer

Potentially useful, but not needed for the current operating loop.

disable

No named job, stale, noisy, or too broad for the value returned.

replace with CLI

A deterministic CLI command is cheaper, clearer, and sufficient.

Potential

Name high-value MCPs by job.

The useful question is not which connector is exciting. It is which job needs structured interactive tool access enough to justify token cost and permission scope.

stackmates-cli

Prefer first.

Planning, demand, receipts, and project state through the commissioned engineering CLI.

Use when: The job is already expressible through the unified drmg entrypoint.

Perplexity

Use for research jobs.

Current web research and cited external intelligence.

Use when: The answer depends on fresh or external evidence that local files cannot provide.

GitHub

Keep if scoped.

Repository, PR, issue, and CI state when structured API access beats shell output.

Use when: The task needs live GitHub objects or cross-repo coordination.

Context7

Use on unfamiliar libraries.

Current framework and library documentation.

Use when: A coding decision depends on API details that may have changed.

Nx

Keep for engineering work.

Workspace graph, project metadata, and affected target context.

Use when: The repo is an Nx workspace and graph context reduces guesswork.

Chrome/browser

Use only when render evidence matters.

Rendered page inspection, screenshots, permissions, and interaction evidence.

Use when: The claim is visual or browser-state dependent.

Vercel

Commission when deploy debugging is frequent.

Deploy previews, runtime logs, and build failure inspection.

Use when: The failure appears only in hosted deployment.

Google Workspace read

Read-only by default.

Calendar, docs, sheets, drive, or mail reading where explicitly commissioned.

Use when: The task depends on workspace context and read scope is approved.

Supabase/Postgres read

Read-only unless separately authorized.

Schema and data inspection for commissioned databases.

Use when: A product or analytics task needs live database facts.

Operating rule

Default to the smallest sufficient tool boundary.

Default to CLI when it is cheaper and sufficient.
Use MCP when structured interactive tool access justifies the token and permission cost.
Never treat a visible connector as commissioned just because a session can see it.
Never copy secrets, tokens, auth cache values, or host-specific config into this repo.
Use .EVOLVE/MCP-TOOLKIT as a staging and evidence lane only; durable operating language belongs on this page.