Resources
nba://apis/catalog, nba://policy/risk-tiers, nba://investigation/{id}/manifest, nba://lineage/{asset}, nba://game/{gameId}/context, nba://artifact/{id}.
Technical due diligence · package 0.4.1 · July 19, 2026
Webhound MCP: how it onboards agents and communicates long-running research.
An auditable SPA that keeps direct evidence separate from interpretation. It covers the public product, the published npm package, client communication patterns, implementation defects, the upcoming MCP draft migration, and an NBA/Core Platform implementation blueprint.
Research posture
Facts are claims directly supported by official documentation, protocol specifications, or inspected package code. Analysis is intentionally isolated and references the fact IDs it depends on.
Verified factDirectly supported by source or code.
Protocol factPrimary MCP specification behavior.
AnalysisInterpretation or inference linked to facts.
RecommendationProposed adoption or remediation action.
30
Published MCP tools
3 + 3
Resources and prompts
110s
Maximum bounded wait
58
Documented REST endpoints
Central conclusion
Webhound's package is best understood as a semantic control plane over a REST research service. Its key innovation is not transport. It is executable onboarding plus state-aware guidance that teaches the host agent how to operate a paid, asynchronous, evidence-producing workflow.
Assessment at a glance
Scores are analysis, not vendor facts.
Evidence layer
Verified facts and direct code findings
No recommendations are mixed into this view. Open a card to see sources and package line references.
System model
Architecture and trust boundaries
Confirmed implementation paths are solid. Hosted internals are shown as opaque because they are not present in the published package.
MCP hostClaude, Cursor, Codex, ChatGPT, VS Code or another client.
Local package`npx webhound-mcp`; MCP JSON-RPC over stdio. Hosted clients use a separate remote endpoint.
Webhound REST API v2Bearer auth, 58 documented endpoints, session lifecycle and artifacts.
Opaque research runtimePlanner → executor → verifier, billing, data stores, hosted OAuth and policy enforcement.
Confirmed boundary
The npm package validates inputs, shapes tools, adds client guidance, calls the Webhound API, and maps backend session state into MCP results.
Not independently verified
The hosted MCP gateway, token exchange, backend research agents, authorization enforcement, billing idempotency, and tenant isolation are outside the published package.
Transport variants
Local stdio
The host spawns the npm binary. Credentials arrive via environment variables. The process communicates exclusively through standard input and output.
Hosted Streamable HTTP
The README names a hosted URL and OAuth flow. The local package exports a stateless HTTP adapter, but the production hosted server implementation is unavailable.
Trust boundary map
Local workspaceFiles, memory, rules and private context stay local until approved.
Explicit selectionUser or policy selects approved files, sessions or context.
MCP adapterValidates and relays selected content and operations.
Webhound serviceProcesses uploaded context and produces evidence artifacts.
Client protocol
How Webhound communicates with the client
The server communicates behavior through multiple MCP surfaces rather than tools alone.
1. Server instructions
Global operating policy: when to use the service, budget semantics, completion rules, polling behavior, privacy, steering and recovery.
2. Tool descriptors
Names, schemas, read/write hints, destructive/open-world hints, OAuth schemes and host-specific invocation messages.
3. Resources and prompts
Reference material and reusable report, dataset and troubleshooting entry points without overloading tool descriptions.
4. Tool results
Short model-visible summary plus structured state, next action, runtime estimate, onboarding message, alerts and evidence metadata.
Representative sequence
User
“Set up Webhound”
Answers one onboarding question
Approves first research brief
MCP host / model
tools/call onboarding
Presents immediate_next_message
tools/call start_report
watch / wait later
webhound-mcp
GET /mcp/onboarding
Structured onboarding state
POST /research
Session ID + next-action guidance
GET status + diagnostics
Webhound backend
Account/default state
Creates durable session
Planner → executor → verifier
Status, alerts, completion
Result shape
// Representative pattern reconstructed from package helpers { content: [{ type: "text", text: "Session is still running…" }], structuredContent: { status: "running", done: false, runtime_estimate: { recommended_next_check_seconds: 600 }, sidecar_guidance: { note_tool: "webhound_add_sidecar_notes" }, mcp_next_action: "wait" }, isError: false }
First-run design
Executable MCP onboarding
Installation makes tools available. Onboarding establishes the behavioral contract.
Install globallyAdd npx server and key to host configuration.
Restart host sessionMany clients load MCP servers only at session start.
Call onboardingNo file inspection or memory lookup first.
Follow next messageAsk one question, wait, then transition.
Start first runOptionally install local usage and budget rules.
Mechanical setup
Command, environment credential, config location, restart, and tool discovery.
Behavioral activation
Account-aware dialogue, privacy constraints, workspace targeting, budget policy, first use, and later check-ins.
Onboarding contract observed in code
Host obligations
Do not summarize account state. Send the immediate next message. Ask one question. Do not inspect local context until permission and target are established.
Server obligations
Return account/default/free-run state, the next user message, workspace-rule guidance, budget policy, and the intended next tool or dialogue transition.
Privacy behavior
Workspace rules, memories, files and private notes should not be transmitted to Webhound merely to complete setup.
First-run continuity
After starting research, handle local setup or schedule a later check-in rather than entering a visible tight polling loop.
Reusable onboarding result contract
interface OnboardingResult {
onboarding_version: string;
state: "ready" | "needs_auth" | "needs_workspace_consent" | "needs_policy";
immediate_next_message: string;
next_action: "ask_user" | "authenticate" | "start_first_run";
allowed_next_tools: string[];
forbidden_next_tools: string[];
account?: { tenant_id: string; entitlements: string[] };
policy?: { max_risk_tier: string; approval_required_for: string[] };
}Long-running work
Session lifecycle and recovery
Webhound uses durable backend session IDs and explicit status tools instead of the MCP Tasks primitive.
CreatedReport or dataset accepted.
RunningPlan, search, execute, verify.
Awaiting inputHost asks user and sends checkpoint answer.
Running againResume with new input or budget.
Completeddone=true and final evidence available.
Credit exhaustedBilling recovery before retry or resume.
StoppedExplicit user cancellation.
Failed / emptyDo not present as success.
Watch
Single status and diagnostics snapshot with next-action guidance.
Wait
Bounded polling for short remaining intervals. Returns after a maximum of 110 seconds.
Scheduled check-in
For longer runs, the result recommends a later heartbeat rather than visible repeated polling.
Completion invariant
`done=true` is authoritative. `output_ready=true`, partial documents, spend, or elapsed time do not independently mean the run is finished.
Tasks migration path
Capable clients
Start with task augmentation, poll with `tasks/get`, answer input-required states, cancel with `tasks/cancel`, and retrieve final results with `tasks/result`.
Compatibility clients
Continue exposing start, watch, wait, output and cancel tools mapped to the same backend session.
Published surface
Tool, resource and prompt catalog
The catalog is grouped by functional purpose and side-effect profile.
| Tool | Category | Effect | Purpose |
|---|
30
Tools
3
Resources: guide, pricing, status
3
Prompts: report, dataset, troubleshoot
Direct inspection
Implementation findings
These are code observations from the published 0.4.1 tarball. Interpretation appears only in the analysis view.
Package shape
2,412 total lines across README, executable, MCP server, HTTP adapter and API client. Two runtime dependencies.
API attribution
Tool name and package version are propagated as REST headers for observability.
Result strategy
Concise text for the model, full object in structuredContent, and optional host-specific metadata.
Transport strategy
stdio executable plus an exported stateless Streamable HTTP request handler.
Confirmed defect: health false positive
// Each request converts failure into a normal value. const [health, credits, defaults, freeRun] = await Promise.all([ this.get('/health').catch(error => ({ error: error.message })), this.get('/account/credits').catch(error => ({ error: error.message })), this.get('/mcp/defaults').catch(error => ({ error: error.message })), this.get('/mcp/free-run').catch(error => ({ error: error.message })) ]); // The outer catch is not reached for those failures. return { authenticated: true, health, credits, defaults, free_run: freeRun };
Other notable implementation choices
Permissive schemas
Every tool defaults to a passthrough object output schema rather than a field-level contract.
Private SDK patch
The server rewrites the internal `tools/list` request handler to expose security metadata at the top level.
Billing recovery
HTTP 402 becomes structured user guidance but is returned with MCP `isError=false`.
Full session retrieval
One tool intentionally returns the entire canonical session without pagination or truncation.
Interpretation layer
Analysis linked to evidence
Every item cites the fact IDs used. Items marked as risks or opportunities are not vendor claims.
Enterprise review
Risk register
Prioritized from the inspected adapter and the gaps between documented behavior and enterprise control requirements.
| ID | Risk | Level | Likelihood | Impact | Evidence | Recommended control |
|---|
Application
What we should learn and adopt
A prioritized enterprise MCP blueprint derived from Webhound's strengths and implementation gaps.
Recommended enterprise flow
Identity and capabilitiesOIDC/workload identity, client capability negotiation.
Executable onboardingAccount, policy, consent, workspace scope and next step.
Policy + approvalRisk tier, data class, exact operation and budget receipt.
Task executionDurable task/session with progress, input and cancellation.
Evidence resultBounded manifest, selected artifacts, claims, sources and audit trail.
Canonical result envelope
interface GovernedToolResult<T> {
operation_id: string;
status: "accepted" | "working" | "input_required" | "completed" | "blocked" | "failed" | "cancelled";
action_started: boolean;
side_effect_occurred: boolean;
spend_occurred: boolean;
data?: T;
next: {
action: "none" | "poll" | "ask_user" | "request_approval" | "retrieve_result";
poll_after_ms?: number;
user_message?: string;
allowed_tools?: string[];
forbidden_tools?: string[];
};
provenance: {
tool: string;
server_version: string;
policy_version: string;
request_id: string;
trace_id: string;
actor_id: string;
tenant_id: string;
};
}Official draft · research cutoff July 19, 2026
Upcoming MCP specification
Facts from the official draft are separated from migration interpretation. The current released baseline remains 2025-11-25; draft details may still change before publication.
DRAFT
Do not treat this as a production-stable wire contract yet.
Use it to shape architecture, add compatibility seams and build conformance fixtures. Pin final schemas and SDKs only after the release is cut.
22
Verified draft facts
9
Major breaking areas
3
Result modes: complete, input, task
0
Required protocol sessions
Verified facts
Directly grounded in the official draft specification, final SEPs and official extension documentation.
Released-to-draft delta matrix
A compact view of the migration surface. “Breaking” means wire or lifecycle behavior changes, not necessarily a breaking product capability.
| Area | 2025-11-25 baseline | Upcoming draft | Impact |
|---|
Analysis for Webhound
These are migration inferences, not MCP project or Webhound claims. Each card links to the supporting draft facts.
Most important interpretation
The new protocol formalizes the architecture Webhound was approximating with backend session IDs, watch/wait tools and explicit next actions. The migration should preserve those domain semantics while replacing bespoke lifecycle plumbing with MRTR and Tasks where clients support them.
Webhound feature migration
Dual-stack migration plan
A staged pattern that protects existing clients while introducing stateless requests, MRTR, the Tasks extension, stronger authorization and explicit caching.
Migration strategy
Do not rewrite domain behavior around a draft SDK. First create a protocol-neutral operation model. Then place released and draft MCP adapters in front of the same domain services.
Target compatibility architecture
Clients
2025-11-25 hostsDraft-capable hostsTasks-capable hostsText-only fallbacks
Protocol gateway
Legacy initialize adapterserver/discover adapterCapability detectorResult serializerStream/subscription adapter
Governance
Identity contextPolicy decisionApproval receiptsScope challengeAudit + OTel
Domain services
Onboarding stateResearch orchestrationEvidenceBudgetSteeringArtifacts
Durable stores
Operation ledgerTask stateResearch sessionsIdempotency recordsEvidence manifests
Migration phases
Each phase has a measurable exit criterion. Later phases can be developed in parallel, but production enablement should retain this dependency order.
Webhound feature mapping
How each current semantic feature maps to the new protocol without losing its product intent.
| Feature | Current pattern | Draft-native pattern | Migration note |
|---|
Compatibility matrix
Protocol version and extension support are independent decisions.
| Client | Server | Expected behavior | Support posture |
|---|
Protocol-neutral TypeScript result
type OperationResult<T> =
| { resultType: "complete"; data: T; meta: ResultMeta }
| { resultType: "input_required";
inputRequests: Record<string, InputRequest>;
requestState: string; meta: ResultMeta }
| { resultType: "task";
taskId: string; status: TaskStatus;
ttlMs: number | null; pollIntervalMs?: number;
meta: ResultMeta };
interface RequestContext {
protocolVersion: string;
capabilities: ClientCapabilities;
actor: ActorIdentity;
tenantId: string;
trace: TraceContext;
idempotencyKey?: string;
}Dual adapter dispatch
async function handleMcp(request: JsonRpcRequest, http: HttpContext) {
const wire = detectWireProtocol(request, http.headers);
const context = await normalizeRequestContext(wire, request, http);
const domainRequest = adapters[wire].toDomain(request, context);
const result = await domainRouter.execute(domainRequest, context);
// One domain result; version-specific serialization.
return adapters[wire].fromDomain(result, context);
}Do not perform a flag-day SDK upgrade
The draft changes lifecycle, transport, results, Tasks and authorization at once. A direct package bump would mix protocol defects with product regressions.
Best cutover signal
Retire a fallback only when real telemetry shows supported client adoption, successful task completion, no cross-tenant authorization defects and proven rollback.
Design proposal · NBA and Core Platform APIs
Blueprint for a governed NBA Core Platform MCP
This is a proposed architecture derived from Webhound's strongest patterns and the upcoming MCP draft. It is not a description of an existing NBA implementation.
Product thesis
Build a semantic, identity-bound control plane over NBA and Core Platform APIs—not a generic API proxy.
The MCP server should guide agents through discovery, investigations, evidence collection and approved operations. It should hide downstream API quirks, enforce policy before execution and make every conclusion traceable.
Design principles
The proposal retains Webhound's executable onboarding and evidence model while correcting its schema, authorization, tool-count and lifecycle weaknesses.
Reference architecture
Clients
VS Code / CopilotClaude / Cursor / CodexChatGPTCopilot StudioCLI and automation
MCP edge
Streamable HTTPstdio developer bridgeLegacy + draft adaptersserver/discoverOptional Apps
Identity & policy
Enterprise IdPToken brokerTenant + environmentRisk classifierApproval serviceData egress policy
Orchestration
Onboarding state machineTask serviceInvestigation plannerEvidence graphArtifact serviceQuota manager
Domain adapters
API catalog + contractsContent and game dataData lineageObservabilityCIAM / identityCache and deliveryJira / Confluence
Evidence & telemetry
Operation ledgerFindings + sourcesS3 artifact storeDynamoDB task stateOpenTelemetryImmutable audit events
Webhound-to-NBA capability translation
The conceptual equivalence is useful, but the NBA implementation substitutes enterprise risk and data governance for Webhound's monetary budget model.
| Webhound pattern | NBA/Core capability | Purpose |
|---|
Recommended public tool surface
Fourteen tools is enough to express the primary workflows without publishing every downstream API route as an MCP tool.
| ID | Tool | Effect | Risk | Purpose |
|---|
Resources, prompts and Apps
Use each MCP primitive for the job it handles best. Apps are optional enhancements with complete non-UI fallbacks.
Prompts
incident_triage, api_integration_plan, content_research, release_readiness, lineage_impact_analysis, postmortem_draft.
MCP Apps
Investigation dashboard, lineage explorer, evidence review, approval center, API contract explorer and game/content context viewer.
Skills / workspace guidance
Client-local instructions for coding standards and domain conventions. The server remains authoritative for policy, identity, current capabilities and operation state.
Risk tiers and action policy
Tool annotations improve UX but do not enforce security. The policy decision point must independently evaluate every operation.
| Tier | Examples | Default control |
|---|
Governed operation envelope
interface GovernedResult<T> {
resultType: "complete" | "input_required" | "task";
operationId: string;
status: "accepted" | "working" | "blocked" | "completed" | "failed";
actionStarted: boolean;
sideEffectOccurred: boolean;
data?: T;
next?: { action: string; pollAfterMs?: number; userMessage?: string };
provenance: {
actor: string; tenant: string; environment: string;
policyVersion: string; decisionId: string;
traceId: string; sourceIds: string[];
};
}Bound approval receipt
interface ApprovalReceipt {
approvalId: string;
actorSubject: string;
tenantId: string;
operationHash: string;
riskTier: "T3" | "T4" | "T5";
environment: "dev" | "qa" | "uat" | "prod";
expiresAt: string;
oneTimeUse: true;
signature: string;
}Deployment pattern
A forward-compatible AWS-oriented shape. Exact service selection remains an implementation decision.
Stateless request plane
TypeScript MCP gateway on Lambda or containers. Any instance can handle any request because durable state is external and explicit.
Long-running work plane
Task orchestrator backed by durable workflow execution, queues and workers. Task IDs map to investigation state rather than transport connections.
Optional subscription plane
Use a containerized long-lived HTTP path only when clients need subscriptions/listen. Normal tools and tasks do not depend on it.
Policy and identity
Enterprise IdP, OAuth protected-resource metadata, audience-bound tokens, policy engine and an independent approval service.
Evidence and artifacts
Immutable operation ledger, object storage for large artifacts, structured findings and bounded manifests for model context.
Observability
W3C trace context through MCP _meta, downstream API spans, tenant-safe metrics and audit events tied to every policy decision.
Rollout sequence
Start with high-value read workflows. Introduce mutation only after the identity, policy, audit and approval layers have production evidence.
Internal-ready first
API discovery, contracts, approved game/content context, lineage manifests, service ownership and bounded health summaries.
Additional vetting required
Raw logs with user data, CIAM administration, cache invalidation, production configuration, content publishing, broad exports and partner/public exposure.
What not to copy from Webhound
Do not use a 30-tool flat catalog, long-lived keys in project config, permissive output schemas, model-asserted approval booleans, private SDK patches, unbounded session payloads or ambiguous success responses for blocked billing or policy states.
Provenance
Source ledger and methodology
Primary sources were favored. Package observations come from the published npm tarball rather than third-party summaries.
Methodology
Official Webhound pages were reviewed for product claims. The `webhound-mcp@0.4.1` npm tarball was downloaded and inspected line by line. The declared GitHub repository was checked. MCP behavior was compared with the official November 25, 2025 specification. Facts and code findings were recorded first; analysis and recommendations were produced afterward and reference fact IDs.
Limitations
No authenticated Webhound account was used. The hosted MCP endpoint, OAuth exchange, backend planner/executor/verifier implementation, billing ledger, tenant isolation, and production authorization logic were not available for direct inspection. Product claims about those layers are labeled accordingly.