@jisuapi/mcp

Official MCP (Model Context Protocol) server for jisuapi.com Agent Gateway.

This npm package converts MCP tools/call requests into HTTPS calls against POST /agent/search and POST /agent/execute, so AI clients like Cursor and Claude Desktop can discover and invoke any jisuapi tool with structured parameters.

Spec reference: jisuapi Agent 网关与 MCP 实施级技术规格书 v1.8.1 §14

Install

npm install -g @jisuapi/mcp

Or run with npx (no global install needed):

JISUAPI_KEY=YOUR_APPKEY npx @jisuapi/mcp

Environment variables

| Variable | Required | Default | Notes | |----------------------|----------|-----------------------------|---------------------------------------------------------| | JISUAPI_KEY | yes | - | Your jisuapi APPKEY (Bearer token) | | JISUAPI_BASE_URL | no | https://api.jisuapi.com | Override only for staging | | JISUAPI_TIMEOUT_MS | no | 20000 | Per-request HTTPS timeout |

The package will never read credentials from a file in the repo or package.json; the only supported path is environment variables.

Cursor integration

Add this to ~/.cursor/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "jisuapi": {
      "command": "npx",
      "args": ["-y", "@jisuapi/mcp"],
      "env": {
        "JISUAPI_KEY": "YOUR_APPKEY"
      }
    }
  }
}

Restart Cursor; the three tools jisuapi_search, jisuapi_execute, jisuapi_get_tool will appear in the MCP tools panel.

Claude Desktop integration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "jisuapi": {
      "command": "npx",
      "args": ["-y", "@jisuapi/mcp"],
      "env": {
        "JISUAPI_KEY": "YOUR_APPKEY"
      }
    }
  }
}

Restart Claude Desktop.

Exposed MCP tools

jisuapi_search

Discover tools by natural-language query or category.

Input:

{ "query": "查询手机号归属地", "limit": 5 }

jisuapi_execute

Invoke a specific tool by tool_id.

Input:

{
  "tool_id": "shouji_query",
  "params": { "mobile": "13800138000" },
  "idempotency_key": "optional-uuid-for-safe-retry"
}

Retry policy: this client never auto-retries execute. If you need safe retries, pass an idempotency_key and let the gateway dedupe. (Spec §14.3)

jisuapi_get_tool

Look up a single tool's metadata by tool_id.

Error handling

Errors from the gateway are returned as MCP tool errors with the JSON payload { status, msg, error_msg, request_id }. See spec §6 for the full code table:

| status | msg | meaning | |--------|------------------------|------------------------------------------| | 100 | APPKEY_EMPTY | JISUAPI_KEY env not set | | 101 | APPKEY_INVALID | APPKEY rejected by gateway | | 102 | TOOL_NOT_FOUND | tool_id doesn't exist or is disabled | | 103 | RATE_LIMITED | QPS exceeded | | 104 | QUOTA_EXCEEDED | daily free-tier quota exhausted | | 106 | INSUFFICIENT_BALANCE | paid tool with empty balance + no plan | | 107 | INVALID_PARAM | parameter validation failed | | 109 | AGENT_DISABLED | account hasn't enabled the Agent Gateway | | 110 | DAILY_CAP_REACHED | per-day spend cap hit | | 111 | UPSTREAM_TIMEOUT | upstream API timed out | | 112 | UPSTREAM_ERROR | upstream API returned non-zero status | | 113 | INTERNAL | gateway-side error |

Local development

cd mcp
npm install
npm run build
JISUAPI_KEY=YOUR_APPKEY node dist/index.js

The MCP server speaks JSON-RPC over stdio. To smoke-test outside an MCP client you can pipe a tools/list request manually, but it's easier to wire it into Cursor / Claude Desktop with the configs above.

Repository layout

mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          stdio MCP server
│   ├── client.ts         HTTPS client for /agent/*
│   ├── env.ts            JISUAPI_KEY / JISUAPI_BASE_URL
│   └── tools/
│       ├── search.ts
│       ├── execute.ts
│       └── getTool.ts
└── README.md

When this module is ready for npm publish, it will be lifted out of the main jisuapi repo into a standalone GitHub repository jisuapi/mcp-server via:

# From the jisuapi repo root
git subtree split --prefix=mcp -b mcp-export
# push the mcp-export branch to a fresh repo, then publish from there

See mcp/PUBLISH.md for the full publish runbook.

License

MIT