explain_architecture
See how requests, auth, and integrations connect—before you edit the wrong layer.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents a structured architecture map through explain_architecture—entry points, auth strategy, external services, flow paths, and optional health scoring—with nine other tools and one API key.
When to use
- “How does auth work?” or “what happens on checkout?”—end-to-end flow questions.
- Before changing auth, billing, webhooks, rate limits, or database layers.
- Onboarding to an unfamiliar repo (local path or github:owner/repo).
- Pre-deploy or refactor review—mode audit for health_score and anti_patterns.
When not to use
- You only need stack and npm scripts—use get_project_context.
- You know the exact file and function—use read_code.
- You need every occurrence of a string—use find_code.
- Tiny repos under ~10 files or a one-line edit.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| path | string | Yes* | Absolute path or github:owner/repo. |
| project_path | string | No | Alias for path. |
| inline_files | object | No* | path → contents if no disk. |
| focus | enum | No | auth | api | database | security | data_flow | error_handling | full |
| mode | enum | No | overview | deep | audit |
| detail_level | enum | No | minimal | standard | full |
| exclude | string[] | No | Extra ripgrep exclude globs. |
Limits: Heuristic detection—not a substitute for LSP or runtime tracing. Large repos auto-scope to overview. Python/Go may show coverage warnings. Does not execute code.
Try it — copy a prompt
Paste into Cursor, Claude Code, Windsurf, VS Code, or any editor with a hosted MCP connection.
Before you call it
- Zephex API key and hosted MCP configured.
- Either **path** (absolute local root or github:owner/repo) or **inline_files** for remote transports—one is required.
- Optional **focus** to narrow (auth, api, security, database, …) and **mode** for depth.
Token and request cost
overview + standard detail is typically 600–1,000 tokens. deep runs more analyzers (~1,500–2,400). audit + full can reach ~2,400–3,400 tokens but still beats manually opening 20+ files (often 15,000–50,000 tokens). Output is capped at 30,000 characters. Repos over ~10k files auto-degrade to overview with a warning.
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "explain_architecture", "arguments": { "path": "/path/to/project", "mode": "overview", "focus": "auth", "detail_level": "standard" } }}Response shape
Response shape
{ "framework": "Next.js", "language": "TypeScript", "architecture_type": "Monolith", "entry_points": [{ "path": "/api/webhooks", "method": "POST", "file": "src/app/api/webhooks/route.ts" }], "auth_flow": { "strategy": "Supabase", "validation_files": ["src/lib/auth.ts"] }, "external_services": [{ "name": "Stripe", "type": "payment", "locations": ["src/lib/stripe.ts:12"] }], "warnings": [], "mermaid": { "service_diagram": "graph TB …" }, "tokens_in_response": 840}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| How does X flow end-to-end? | explain_architecture | read_code |
| Which file has this function? | find_code | explain_architecture |
| Stack + test command | get_project_context | explain_architecture |
| Files to edit for one task | check_test | explain_architecture |
What it can do in your codebase
- Detect framework and language across 16 languages and 30+ frameworks
- List entry_points with file:line (routes, handlers, middleware)
- Map auth_flow: strategy, validation files, token source (23+ auth libraries on Node/TS)
- List external_services with locations—DB, cache, queues, Stripe, Sentry, AI SDKs, etc.
- Trace flow_paths for request → handler → data layers
- Report error_handling, dependency_graph, data_flow by focus/mode
- Generate Mermaid service and auth sequence diagrams
- mode: audit adds anti_patterns and health_score (0–100)
- focus routes analyzers: auth, security, api, database, data_flow, error_handling, full
- Respect exclude globs for vendor/build folders
- Support inline_files when the MCP host has no filesystem
Common response fields
Why teams use it
One map, many subsystems
See auth, payments, and data stores in one call instead of opening every route and middleware file.
Confidence-aware
warnings and dimension_confidence tell the agent when to double-check—not silent empty arrays.
Depth on demand
overview for speed; deep for thorough focus area; audit before risky releases.
Read-only
Does not modify code—only scans. Pairs with check_test then read_code for edits.
Focus areas (focus parameter)
| Field | Meaning |
|---|---|
| focus areas | Narrow which analyzers run (see rows below). |
| focus: auth | entry_points, auth_flow, external_services, flow_paths. |
| focus: security | auth_flow, external_services, error_handling, complexity_hotspots. |
| focus: api | entry_points, service_boundaries, flow_paths, data_flow. |
| focus: database | external_services, data_flow, dependency_graph. |
| focus: full | All analyzers (largest output). |
Task modes
| task | What you get |
|---|---|
| overview | Fast map—core analyzers + service diagram (~600–800 tok). |
| deep | More analyzers for chosen focus + auth sequence diagram. |
| audit | anti_patterns, health_score, complexity_hotspots, dependency graph. |
Analysis depth (mode)
How it fits your workflow
- get_project_context — stack and key_files on a new repo
- explain_architecture — how auth, APIs, and services connect
- check_test — files for your specific change
- read_code — implementations on those files only
Troubleshooting
- Empty external_services on Python/Go → read warnings; Node/TS coverage is deepest—verify manually.
- dimension_confidence low on auth_flow → custom auth; inspect validation_files yourself.
- Huge repo, thin result → pass a subdirectory as path or use focus auth/api instead of full.
- Private GitHub clone fails → configure GitHub access or use inline_files.
How to verify it works
- Connect Zephex MCP; confirm explain_architecture in tools/list.
- Ask: “explain_architecture overview focus auth—list auth_flow.strategy and one entry_point.”
- JSON should include framework or language, entry_points or auth_flow, and dimensions_analyzed listing what ran.
Common questions
Billing and plan limits: FAQ, usage limits.
Which MCP tool should I use to understand how auth works?
Use explain_architecture with focus auth (mode overview or deep). Read auth_flow.strategy and auth_flow.validation_files, then read_code on those paths. get_project_context tells you the stack; explain_architecture tells you the flow.
What is the difference between explain_architecture and check_test?
explain_architecture maps how the whole system is wired (routes, auth, integrations). check_test picks files for one task you describe. Use architecture for “how does it work?”; use check_test for “what should I open to implement X?”
How do I use explain_architecture with Cursor?
Add Zephex hosted MCP, restart, and ask for an architecture overview before big changes. Example: “explain_architecture mode overview focus api on this workspace.” Then follow entry_points and external_services locations with read_code.
When should I use mode audit?
Before demos, releases, or large refactors when you want health_score, anti_patterns, and complexity_hotspots. It costs more tokens than overview but surfaces god files, circular deps, and weak error-handling signals.
What does focus security do?
Runs auth_flow, external_services, error_handling, and complexity_hotspots—roughly 40% smaller than focus full while keeping what security reviews need. Good for “is this safe to deploy?” questions.
Does explain_architecture work on GitHub URLs?
Yes—pass github:owner/repo or an HTTPS URL. The server shallow-clones with SHA-keyed cache. Private repos need GitHub access configured on Zephex; otherwise use inline_files.
Ready to test? check_test runs tests and returns structured health.
Billing: Each tool call counts as one request on your Zephex plan (Free includes 555 requests/month). See usage limits for tier details. Usage limits.
Data: Scans source paths you authorize; results are ephemeral and not used for model training. Data use.
get_project_context is manifest-first orientation; explain_architecture traces how the running system is wired—library docs live elsewhere (see Zephex vs Context7.
For AI agents (JSON)
{"tool":"explain_architecture","when":"cross-cutting flow or unfamiliar repo","then":["check_test","read_code"]}