Repository navigation
Import an API
devlomingo edited this page Nov 16, 2026
·
1 revision
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>-
Parses the spec (local
$refs resolved; bundle external ones first). - 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.
-
Flags findings: missing
operationId, descriptions or schemas, and instruction-like text in descriptions (tool poisoning). -
Verifies every read operation with a live call. Write operations are
never called. Skip with
--no-live. - Leaves the version awaiting your approval.
| 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 |
| 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.
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)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 shopRequests 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-networkToolsmith never invents endpoints or guesses a base URL.
Full details, including gRPC type mapping: API-INTEGRATION.md.
toolsmith-mcp · MIT · Repository · Report an issue · Changelog
Getting started
Using it
Operating it
Links