uapi-mcp: Instructions file for Codex

AGENTS.md — uapi-mcp

This file tells AI coding agents (Codex, Claude Code, Cursor, OpenCode, Gemini, etc.) what this repository is and how to wire up the UAPI MCP server.

What this repo is

The official MCP (Model Context Protocol) server for the public API platform uapis.cn. It exposes 100+ UAPI endpoints — network lookups, text utilities, image processing, social-platform queries, translation, search, weather, time, OCR — as MCP tools that any MCP-aware AI agent can call directly.

Hosted server (recommended)

A managed Streamable-HTTP MCP server is already running. Most agents only need this one URL:

https://uapis.cn/mcp

Discovery shortcuts:

• Server card: https://uapis.cn/.well-known/mcp/server-card.json
• WebMCP descriptor: https://uapis.cn/.well-known/webmcp
• Agent card: https://uapis.cn/.well-known/agent-card.json

Wiring it into common agents:

// Claude Desktop / Claude Code (claude_desktop_config.json)
{
  "mcpServers": {
    "uapi": {
      "transport": "streamable-http",
      "url": "https://uapis.cn/mcp"
    }
  }
}

// Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "uapi": {
      "url": "https://uapis.cn/mcp"
    }
  }
}

For paid endpoints, set the UAPI key once via the X-API-Key header (MCP servers may forward mcpAuth.bearer to this header — see the server card for details).

Local install (npm)

The same server is published on npm and runs over stdio for local agents:

# Run directly (no install)
npx -y uapi-mcp start --mode dynamic

# Or install globally
npm i -g uapi-mcp
uapi-mcp start --mode dynamic

Stdio config example:

{
  "mcpServers": {
    "uapi": {
      "command": "npx",
      "args": ["-y", "uapi-mcp", "start", "--mode", "dynamic"]
    }
  }
}

Build from source

git clone https://github.com/AxT-Team/uapi-mcp
cd uapi-mcp
npm install
npm run build
node ./bin/mcp-server.js start --mode dynamic

Available tools