MCP Best Practices

​

Start with an explicit contract

1. Objective: The decision or output the workflow must produce.
2. Scope: Domains, hosts, IP ranges, organizations, or CVEs the client may query.
3. Tools: The FullHunt tools the client may call.
4. Evidence: Fields and timestamps that must be preserved.
5. Stopping condition: The point at which the client must stop calling tools.

Objective: enrich one IP for incident triage.
Scope: 192.0.2.10 only.
Tools: nexus_ip_lookup, nexus_tor_check_ip, intel_ip_to_hosts.
Evidence: preserve returned timestamps and source fields.
Stop: after one successful call to each available tool.

​

Separate observations from analysis

{
  "observations": [],
  "analysis": [],
  "missing_data": [],
  "sources": []
}

​

Control active operations

• Require a user confirmation immediately before a scan call.
• Match the requested target against an allowlist outside the model.
• Use only assets you own or are explicitly authorized to test.
• Record the user, target, purpose, and tool call.
• For OEM scans, retain scan_id and use oem_scan_status with bounded polling.
• Do not poll standard or Enterprise scans through a nonexistent status tool.

​

Keep state outside the conversation

​

Handle limits and failures

• Call auth_status before large workflows.
• Set a maximum number of tool calls per run.
• Retry 429 and transient 5xx responses with exponential backoff and jitter.
• Do not retry 400, 401, or 403 until the request or configuration changes.
• Cache stable WHOIS, organization, and advisory data according to your freshness needs.
• Stop paginating when response metadata indicates the final page.

​

Protect credentials and sensitive data

• Keep X-API-KEY out of prompts, repositories, traces, and screenshots.
• Use a user-level client configuration or secrets manager.
• Redact passwords and unnecessary personal fields from dark-web results.
• Limit retention and access to credential-exposure data.
• Rotate keys after exposure or staff access changes.

​

Design multi-step research

1. Search a CVE.
2. Confirm affected products and fixed versions.
3. Search exploit and advisory records.
4. If Enterprise access exists, compare the product evidence with observed assets.
5. Return matches, non-matches, and uncertain matches separately.

​

Validate production workflows

• Test with a fixed input and expected response shape.
• Verify each tool name against the 63-tool reference.
• Confirm plan and module behavior with a non-production key.
• Set time, pagination, retry, and tool-call limits.
• Review data retention and authorized-scope controls.
• Add alerts for repeated authentication, entitlement, or rate-limit failures.