Skip to content

Import an API

devlomingo edited this page Nov 16, 2026 · 1 revision

Import an API

One command turns an API description into reviewed, typed MCP tools:

toolsmith-mcp import <spec file or URL> --name <name> [auth flags]
toolsmith-mcp show <name>
toolsmith-mcp approve <name>

What import does

  1. Parses the spec (local $refs resolved; bundle external ones first).
  2. Generates one tool per operation with a strict input schema, an output schema where documented, and an access level: GET/HEAD/OPTIONS → read, POST/PUT/PATCH → write, DELETE → destructive.
  3. Flags findings: missing operationId, descriptions or schemas, and instruction-like text in descriptions (tool poisoning).
  4. Verifies every read operation with a live call. Write operations are never called. Skip with --no-live.
  5. Leaves the version awaiting your approval.

Supported sources

Source How
OpenAPI 3.0/3.1, Swagger 2.0 toolsmith-mcp import ./openapi.yaml --name shop
Postman collection v2.0/2.1 toolsmith-mcp import ./shop.postman_collection.json --name shop
Plain endpoint list One line per endpoint, e.g. GET /users/:id/orders A customer's orders, plus --base-url
GraphQL "type": "graphql" in config; the endpoint is introspected. Queries → read, mutations → write
gRPC "type": "grpc" with .proto files or "reflection". Unary and server-streaming methods become tools
Other MCP servers upstreams in config; their tools are re-exposed under a prefix
Free-text docs Optional LLM stage, off by default

Authentication toward your API

Type Flag
Bearer --token-env SHOP_TOKEN
API key --api-key-env NAME [--api-key-header X-API-Key]
Basic, OAuth 2.0 client credentials config only

Secrets are referenced as ${env:NAME}, read when a request is sent, never stored, and redacted everywhere they could appear.

Approve what agents may use

toolsmith-mcp approve shop                                     # read-only tools
toolsmith-mcp approve shop --allow-writes                      # also POST/PUT/PATCH
toolsmith-mcp approve shop --allow-writes --allow-destructive  # also DELETE (each call still needs approval)

Update and roll back

Re-running import on a changed spec creates a new version; the published one stays live until you approve the new one.

toolsmith-mcp rollback shop      # previous approved version
toolsmith-mcp disable shop       # hide all its tools now
toolsmith-mcp enable shop

Local or private APIs

Requests to localhost and private networks are blocked by default. For a local API, allow it for that integration only:

toolsmith-mcp import ./spec.json --name local --base-url http://localhost:8080 --allow-private-network

Toolsmith never invents endpoints or guesses a base URL.

Full details, including gRPC type mapping: API-INTEGRATION.md.

Clone this wiki locally