Claude / Cursor Setup

This guide explains how to connect TestNet as an MCP (Model Context Protocol) server for Claude Code, OpenCode, or Cursor IDE (other clients supporting SSE / streamable MCP can follow the same configuration pattern).

Prerequisites

1. The TestNet backend is deployed and running (default port 8081)
2. You have TestNet access credentials:
   • Recommended: a static MCP API Key (TESTNET_MCP_API_KEY; dev-environment default default-mcp-api-key-for-dev-environment, never expires, optimized for Agents)
   • Alternative: a JWT Token obtained by logging in with a platform user account (requires mcp:view and mcp:execute permissions)

---

Quick Configuration

1. Claude Code Integration

Method A: One-Step CLI Registration (Recommended)

Run the following command in your terminal to register the MCP server:

# Using a static API Key (recommended)
claude mcp add --transport sse testnet http://localhost:8081/mcp/v1 --header "Authorization: Bearer default-mcp-api-key-for-dev-environment"

Method B: Project-Level Configuration File

Create — or reuse the preset — .mcp.json or .claude/settings.json in your project root:

{
  "mcpServers": {
    "testnet": {
      "url": "http://localhost:8081/mcp/v1",
      "headers": {
        "Authorization": "Bearer default-mcp-api-key-for-dev-environment"
      }
    }
  }
}

---

2. OpenCode Integration

Create an opencode.json file in your project root:

{
  "$schema": "https://opencode.ai/config.schema.json",
  "mcp": {
    "servers": [
      {
        "name": "testnet",
        "type": "sse",
        "url": "http://localhost:8081/mcp/v1/sse",
        "headers": {
          "Authorization": "Bearer default-mcp-api-key-for-dev-environment"
        }
      }
    ]
  }
}

After starting OpenCode, the 14 core facade tools (prefixed with testnet_*, each covering a complete business domain via an action parameter) appear in the toolbox automatically.

---

3. Cursor IDE Integration

1. Open Cursor Settings (Ctrl + , or Cmd + ,)
2. Navigate to "Features" ➔ "MCP"
3. Click "+ Add New MCP Server":
   • Name: testnet
   • Type: url
   • URL: http://localhost:8081/mcp/v1
4. Add a header:
   • Key: Authorization
   • Value: Bearer default-mcp-api-key-for-dev-environment
5. Click "Save".

---

Self-Correction Protocol

When a tool execution fails, the TestNet MCP server returns not only the error reason but also a structured remediation hint:

{
  "isError": true,
  "error": "target not found in the asset library of project [proj-1]: example.com (DOMAIN)",
  "remediation": {
    "suggestion": "The workflow requires a seed asset in the library first. Call testnet_asset(action='create') to register the target.",
    "recommendedTool": "testnet_asset",
    "exampleArguments": {
      "action": "create",
      "projectId": "proj-1",
      "assetType": "DOMAIN",
      "data": { "domain": "example.com" }
    }
  }
}

External AI Agents (Claude Code, OpenCode, etc.) can capture this structure and close the self-healing loop directly from recommendedTool and exampleArguments, without re-planning a long reasoning chain.

---

Agent Tool-Calling Best Practices

1. Project context first: everything depends on projectId; prefer the idempotent testnet_project(action="create", projectName="...").
2. Never tight-poll: after dispatching batch tasks, use testnet_task(action="await") for server-side blocking waits; for lightweight single tools use testnet_task(action="run", wait_timeout_seconds=20) for a synchronous reply.
3. Search before run: before triggering any scan or workflow, call testnet_search_tools to discover available tools and their parameter contracts. Never guess tool names.
4. Context economy: enable compact: true for asset queries and cap pages at limit <= 50.
5. Deep log inspection: when a task fails, call testnet_task(action="logs", taskId="...", limit=200) to inspect the real stdout/stderr.

---

Related Documentation

• MCP Overview — the 14 core facade tools, resources, and prompts
• AI Skill Center — inject skill knowledge cards into your Agent
• AI Memory Management — cross-session persistent Agent memory