MCP Workflow Tips

Once MCP is connected, your AI agent has access to Superpositional's system graph. But the real value comes from using the right tool at the right moment in your workflow. This page covers practical patterns that compound over time.

Start new work with context

Before writing code, ask Superpositional what it already knows about the area you're working in. This grounds your agent in the real system — architecture, dependencies, conventions — instead of letting it guess.

Review your plan before implementing

When you're about to start a feature or refactor, describe your approach and ask for a plan review:

"I'm going to add rate limiting to the webhook handler by adding a token bucket in Redis. Review this plan."

review_plan checks your intent against the system's architecture guards and code graph. It catches structural issues early — boundary violations, dependency concerns, approaches that conflict with existing patterns — before you've written a line of code.

This is most valuable for work that crosses module boundaries or introduces new patterns. If your plan contradicts an existing approach in the codebase, you'll know before you build the wrong thing.

Ask questions to orient yourself

When working in unfamiliar code, use ask to get oriented:

"How does the notification system work? What triggers notifications and where do they get delivered?"

"What's the relationship between the order service and the billing module?"

Answers come back with source references — specific files and line numbers — so you can verify and dive deeper. This is faster than grepping through the codebase and hoping you find the right entry point.

Check system context for an entity

Before modifying a function, class, or module, use system_context to understand what you're about to affect:

"Give me system context for src/services/auth/validate.ts"

This returns the entity's role in the system, what depends on it, what it depends on, and what the implications of changing it are. It's the "look before you leap" step that prevents accidental breakage.

Review code as you go

Use review_diff as a spec-step quality check

When working through a multi-task spec (or any large implementation), use review_diff after completing each logical chunk. You can set this up as an automated hook so it runs after every task completion, giving your agent continuous feedback as it steps through the work.

In tools that support hooks (like Kiro), configure a post-task hook:

Event: postTaskExecution
Action: askAgent
Prompt: "Run review_diff on the current git diff to check the implementation so far. Report any architectural concerns, guard violations, or issues before moving to the next task."

This catches problems incrementally rather than discovering them in a final review after all the code is written. Issues found mid-spec are cheaper to fix — the context is fresh and the affected code is small.

Even without hooks, you can ask for a review at any point:

"Review the diff of what I've built so far."

The review runs the same pipeline as a PR review — guards, structural analysis, blast radius — but you get the feedback before you've even committed.

Review before pushing

Before creating a PR, run your full diff through review_diff:

"Review this diff before I push."

This is your pre-merge quality gate. It runs architecture guards, checks for boundary violations, evaluates blast radius, and flags issues that would otherwise surface in code review. Fixing things before the PR is faster than fixing them after review comments.

Understand impact before changing things

Check blast radius

Before modifying files, use get_blast_radius to see what else is affected:

"What's the blast radius if I change src/handlers/payment.ts and src/models/order.ts?"

This returns the transitive dependents — callers, importers, subclasses, implementors — up to two hops deep. It tells you what tests to run, what documentation might need updating, and what other teams might care about your change.

Diagnose problems faster

Root cause analysis from errors

When you hit an error during development — a stack trace, a failing test, a confusing runtime exception — pass it to diagnose:

"Diagnose this error: TypeError: Cannot read properties of undefined (reading 'userId') at src/middleware/auth.ts:42"

Superpositional traces through the code graph to find the root cause, not just the symptom. It checks what feeds data into that code path, what changed recently, and whether similar failures have occurred before.

Investigate issues before fixing them

When picking up a bug report or issue, use review_issue to get codebase-aware analysis before diving in:

"Investigate issue #234: users report intermittent 500 errors on the checkout page."

This runs the issue description against the code graph — finding relevant code, tracing potential causes, and identifying what areas of the codebase are involved. It's the investigation step that tells you where to look, so you're not guessing.

Surface your next work

Find actionable signals

Use list_signals to see what Superpositional has identified as current risks, emerging issues, or areas that need attention:

"What active signals are there for this repo?"

Signals represent the system's ongoing assessment of risks — test gaps that are growing, architectural patterns being violated repeatedly, reliability concerns that span multiple PRs. They're ranked by severity and trajectory (getting worse vs. stable vs. improving).

This is useful for:

• Starting your day. "What should I work on next?" — signals show what's worsening and needs attention.
• Sprint planning. Surface technical debt and risk areas that aren't captured in your issue tracker.
• Post-feature check. After shipping, see if any new signals emerged from your changes.

Combining tools in sequence

The tools work best in combination. Here's a typical flow for starting a new piece of work:

1. list_signals — see what needs attention, pick a signal to address
2. ask — understand the affected area ("how does this subsystem work?")
3. system_context — check the specific entities involved
4. review_plan — describe your intended fix, get feedback before coding
5. Build the fix — write the code
6. review_diff — check your implementation against guards and architecture
7. get_blast_radius — verify nothing unexpected is affected
8. Push — create the PR with confidence

You don't need all steps every time. A simple bug fix might skip straight to step 5. A complex refactor benefits from all of them.