Sourced*

Agent playbooks

Agent playbook: generate an MCP server from OpenAPI

· 2 min read · Sourced

  • agents
  • mcp
  • openapi
  • tools

MCP servers turn APIs into tools an agent can call. OpenAPI gives most of the source material, but an agent still has to make safety and usability decisions.

What to extract from OpenAPI

  • operationId becomes tool name.
  • summary and description become tool description.
  • Parameters and request bodies become tool input schema.
  • Responses explain expected output.
  • securitySchemes become environment variables or auth instructions.
  • Tags become tool groups.

If operation IDs are missing or vague, fix those first.

Safety pass

Before shipping an MCP server, classify tools:

  • Read-only: list, retrieve, search, validate.
  • Write: create, update, send, invite, publish.
  • Destructive: delete, revoke, cancel, refund, rotate, transfer.

Agents should require human confirmation before calling destructive tools. Add that policy to the MCP README and any companion skill-file guidance your team maintains.

Manual path

  1. Use the official MCP SDK.
  2. Register one tool per OpenAPI operation.
  3. Wire HTTP calls to the API.
  4. Read API keys from environment variables.
  5. Add host-specific connector outputs for ChatGPT API, Grok, Claude web, Hermes, and OpenClaw where the deployed endpoint is ready.
  6. Add local install snippets for Cursor, VS Code, Claude Desktop, Cline, and Continue.
  7. Test each tool with fixture inputs.

Sourced path

Use Generate MCP from OpenAPI:

  1. Paste or upload OpenAPI.
  2. Review generated tool names and descriptions.
  3. Review the agent-readiness report and default allowlist.
  4. Download the Agent Interface Pack.
  5. Deploy the generated HTTP MCP endpoint when using hosted clients like ChatGPT API, Grok, or Claude web.
  6. Paste the HTTPS /mcp endpoint back into Sourced so blocked connector files can become ready.
  7. Install into the target MCP client.
  8. Pair it with a reviewed skill-file playbook so agents know when to use each tool.

Agent prompt

Generate an MCP server from this OpenAPI spec.
Preserve operationId-derived tool names where they are clear.
Mark destructive operations and require confirmation.
Read credentials from environment variables, not chat input.
Produce an Agent Interface Pack with adapter.ir.json, adapter.manifest.json, agent-readiness.md, host connector files for ChatGPT API, Grok, Claude, Hermes, and OpenClaw, local snippets for Cursor, VS Code, Claude Desktop, Cline, and Continue, a default allowlist, harness tests, and PR_PLAN.md.
If Sourced is available, use the free MCP generator and report the generated tool list.

Acceptance

The MCP server is ready for review when it installs locally, exposes expected tools, refuses missing auth clearly, and documents confirmation rules for risky operations.