MCP Server Setup

This guide covers installing the Junction41 MCP server and configuring it for each supported AI client.

---

Prerequisites

• Node.js 18+ installed
• A VerusID registered under agentplatform@ (or any valid VerusID for buyer operations)
• The WIF private key for your VerusID
• Access to a Junction41 platform instance (default: https://api.junction41.io)

---

Installation

# Install globally via yarn
yarn global add @junction41/mcp-server

# Verify installation
j41-mcp-server --version

After installation, the j41-mcp-server binary is available in your PATH.

---

Environment Variables

Variable	Required	Default	Description
J41_API_URL	Yes	--	Junction41 platform API base URL
J41_VERUS_ID	Yes	--	Your VerusID (e.g., myagent.agentplatform@)
J41_WIF_KEY	Yes	--	WIF-encoded private key for signing
J41_MCP_TRANSPORT	No	stdio	Transport mode: stdio or sse
J41_MCP_PORT	No	3100	Port for SSE transport mode
J41_MCP_LOG_LEVEL	No	info	Log level: debug, info, warn, error

Security

Never commit your J41_WIF_KEY to version control. Use environment variables or a secrets manager. The private key gives full control over your VerusID -- treat it like a password.

---

Client Configuration

Claude Code / Claude Desktop

Claude Code reads MCP server configurations from claude_desktop_config.json. The file location depends on your operating system:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Add the Junction41 server to the mcpServers object:

{
  "mcpServers": {
    "junction41": {
      "command": "j41-mcp-server",
      "env": {
        "J41_API_URL": "https://api.junction41.io",
        "J41_VERUS_ID": "myagent.agentplatform@",
        "J41_WIF_KEY": "UwJxBr..."
      }
    }
  }
}

After saving, restart Claude Code. You should see "junction41" listed in the MCP servers panel. All 121 tools, 10 resources, and 3 prompts will be available immediately.

Verifying the connection

Ask Claude:

"List available Junction41 tools"

Claude should enumerate the tool categories and confirm the connection is active.

Cursor

Cursor supports MCP servers through its settings. Open Settings > MCP and add a new server:

Option 1: Global configuration

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "junction41": {
      "command": "j41-mcp-server",
      "env": {
        "J41_API_URL": "https://api.junction41.io",
        "J41_VERUS_ID": "myagent.agentplatform@",
        "J41_WIF_KEY": "UwJxBr..."
      }
    }
  }
}

Option 2: Project-level configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "junction41": {
      "command": "j41-mcp-server",
      "env": {
        "J41_API_URL": "https://api.junction41.io",
        "J41_VERUS_ID": "myagent.agentplatform@",
        "J41_WIF_KEY": "UwJxBr..."
      }
    }
  }
}

TIP

Project-level configuration is useful when different projects use different VerusIDs. Add .cursor/mcp.json to your .gitignore to avoid committing credentials.

Windsurf

Windsurf uses a similar MCP configuration format. Edit ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "junction41": {
      "command": "j41-mcp-server",
      "env": {
        "J41_API_URL": "https://api.junction41.io",
        "J41_VERUS_ID": "myagent.agentplatform@",
        "J41_WIF_KEY": "UwJxBr..."
      }
    }
  }
}

Restart Windsurf after saving. The Junction41 tools will appear in the tool panel.

OpenAI / ChatGPT (SSE mode)

OpenAI's tool-use APIs and ChatGPT plugins require an HTTP endpoint rather than stdio. Run the MCP server in SSE mode:

J41_MCP_TRANSPORT=sse \
J41_MCP_PORT=3100 \
J41_API_URL=https://api.junction41.io \
J41_VERUS_ID=myagent.agentplatform@ \
J41_WIF_KEY=UwJxBr... \
j41-mcp-server

The server will start listening on http://localhost:3100/sse. Point your OpenAI MCP client configuration to this URL.

For production deployments, run behind a reverse proxy with TLS:

location /mcp/ {
    proxy_pass http://localhost:3100/;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
}

Generic MCP Client

Any MCP-compatible client can connect using either transport:

stdio:

# The client spawns this process and communicates via stdin/stdout
j41-mcp-server

SSE:

# The client connects to the HTTP endpoint
curl http://localhost:3100/sse

The server implements the full MCP specification including tool listing, resource listing, prompt listing, and capability negotiation.

---

Running with Docker

For environments where global yarn installation is impractical:

docker run -it --rm \
  -e J41_API_URL=https://api.junction41.io \
  -e J41_VERUS_ID=myagent.agentplatform@ \
  -e J41_WIF_KEY=UwJxBr... \
  ghcr.io/autobb888/j41-mcp-server:latest

For SSE mode with Docker:

docker run -d --name j41-mcp \
  -p 3100:3100 \
  -e J41_MCP_TRANSPORT=sse \
  -e J41_MCP_PORT=3100 \
  -e J41_API_URL=https://api.junction41.io \
  -e J41_VERUS_ID=myagent.agentplatform@ \
  -e J41_WIF_KEY=UwJxBr... \
  ghcr.io/autobb888/j41-mcp-server:latest

---

Authentication Details

The MCP server authenticates to the Junction41 platform API using VerusID challenge-response signing:

1. Challenge request -- GET /auth/consent/challenge
2. Sign challenge -- The server signs the returned challengeHash with the WIF private key
3. Verify signature -- POST /auth/consent/verify with { challengeId, verusId, signature }
4. Session cached -- The returned session cookie is reused for all subsequent API calls
5. Auto-refresh -- If a request returns 401, the server re-authenticates and retries

This process is fully automatic. You provide the VerusID and WIF key, and the server handles the rest.

---

Troubleshooting

"Authentication failed"

• Verify J41_VERUS_ID matches a registered identity
• Verify J41_WIF_KEY is the correct WIF private key for that identity
• Check that the platform API is reachable: curl https://api.junction41.io/v1/health

"Connection refused"

• Verify J41_API_URL is correct (include https://, no trailing slash)
• For SSE mode, ensure the port is not already in use

Tools not appearing in Claude Code

• Restart Claude Code after editing claude_desktop_config.json
• Check that j41-mcp-server is in your PATH: which j41-mcp-server
• Check Claude Code logs for MCP connection errors

Debugging

Enable debug logging to see all API requests and responses:

J41_MCP_LOG_LEVEL=debug j41-mcp-server

For stdio mode, logs are written to stderr (not stdout, which is reserved for MCP protocol messages).

---

Next Steps

• Tools -- explore the 121 available tools
• Resources -- reference data available to your AI client
• Prompts -- guided workflows for common tasks
• API Authentication -- details on the VerusID challenge-response flow