# API Skill MCP

[English](https://unpkg.com/apiskill@latest/docs/mcp.md) / [中文](https://unpkg.com/apiskill@latest/docs/mcp.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/mcp.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/mcp.ja.md)

The MCP server is the native AI Agent interface for querying and maintaining the same OpenAPI documents used by the Web app and CLI.

## Local Codex Configuration

API Skill runs as a stdio MCP server:

```bash
node /Users/dobby/dev/apiskill/scripts/mcp-server.mjs
```

Add this to `/Users/dobby/.codex/config.toml` or keep the project-level `.codex/config.toml` when your Codex client loads project config:

```toml
[mcp_servers.apiskill]
command = "node"
args = ["/Users/dobby/dev/apiskill/scripts/mcp-server.mjs"]
cwd = "/Users/dobby/dev/apiskill"
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true
```

With no cache environment configured, MCP uses the same `~/.apiskill/cache` default as Web and CLI. For project isolation, set one absolute `APISKILL_CACHE_DIR` value and use that exact value for all three processes.

Restart Codex and run `/mcp`. You should see `apiskill` with the tools below.

## Read Tools

- `apiskill_check`: check whether a usable cached OpenAPI document exists and return import examples when it does not.
- `apiskill_help`: show MCP help, available tools, and import examples.
- `apiskill_list_versions`: list cached versions.
- `apiskill_search_endpoints`: search endpoint summaries.
- `apiskill_query_api`: CLI-equivalent query. Single matches can return JSON, raw endpoint data, or CLI config.
- `apiskill_get_endpoint`: get one endpoint with parameters, request body, responses, manual config, and optional raw operation.
- `apiskill_get_ai_context`: get AI-ready Markdown for one endpoint.
- `apiskill_get_schema`: expand a named schema.

## Write Tools

These tools modify `cache/latest-import.json` and `cache/versions/`:

- `apiskill_import_url`: import a direct OpenAPI JSON/YAML URL.
- `apiskill_crawl_openapi`: crawl Swagger UI / Knife4j / Redoc and import the discovered document.
- `apiskill_import_file`: import a local JSON/YAML file.
- `apiskill_import_curl`: execute a curl command and import its OpenAPI response.
- `apiskill_create_document`: create a blank OpenAPI document version for from-scratch API authoring.
- `apiskill_create_api`: create a manual API operation.
- `apiskill_edit_api`: edit/replace a manual API operation.
- `apiskill_delete_api`: delete an API operation.

## Author From Scratch

When a project has no upstream documentation yet, ask the agent to call `apiskill_create_document` first:

```json
{
  "title": "My API",
  "version": "1.0.0",
  "description": "Internal service contract"
}
```

Then add endpoints with `apiskill_create_api`, edit them with `apiskill_edit_api`, and query them with `apiskill_get_endpoint` or `apiskill_query_api`. This lets an AI tool build and maintain a local API contract before any third-party OpenAPI source exists.

## Verify

```bash
npm run mcp
```

For protocol-level verification, initialize the server, call `tools/list`, then call `apiskill_check` and `apiskill_list_versions`. The server should return `serverInfo.name = apiskill-mcp` and list the `apiskill_*` tools.

## Future Server Deployment

The current setup is local stdio. For a server deployment, either start the same stdio server through SSH/remote execution with server-side `APISKILL_ROOT` and `APISKILL_CACHE_DIR`, or add a Streamable HTTP MCP wrapper that calls the same shared core module. Keep tool names and payload semantics stable.