How-to › Use AI to do the integration

How to connect a generated MCP server for a third-party API#

Build the SDK Catalog's Go MCP server for an API from a pinned commit, list its tools over stdio, and check one call and its age before an agent uses it.

Audience
API consumer
Level
intermediate
Topic
Connect MCP clients to servers
Languages
Go
Verified

Read first: Add a stdio MCP server to Claude Code

An agent needs JSONPlaceholder’s posts, and a ready-made MCP server exists for the API. Its install line fails on a replace directive, and its newest tag asks the API for a path that holds no posts. Its list tool returns a result that a client on the official TypeScript SDK refuses, and the tool list gives no sign of any of it.

What you get

You will end up with the SDK Catalog’s MCP server for one API, built from a pinned commit. A check lists its tools and calls one endpoint before you trust it. This is for you if you connect servers you did not write.

Short answer

Build the Voxgig SDK Catalog’s Go MCP server from a go.mod of your own, with a tool directive and a replace that pins one commit. Start it over stdio, list its two read-only tools, and call one known endpoint against a stand-in and once against the live API. Read the generation date from the pinned commit, because the server knows only the OpenAPI document it was generated from.

You will need

Go 1.25 or later, as the server’s module requires, and Node 22 or later for the check scripts, which use only Node’s built-ins. JSONPlaceholder needs no key. For an API that does, the catalog server reads it from an environment variable named after the API, such as JSONPLACEHOLDER_APIKEY.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
GitHub MCP ServerThe vendor publishes and supports its own server, as GitHub doesA GitHub sign-in or token with the permissions you grant, and toolsets to trimThe vendor has no server, or you need offline tests
KiotaYour team already generates its clients with KiotaWrites no MCP server, so you connect a ready-made one or write a facadeYou want one command that yields a server
openapi-mcp-generatorYou hold the API’s OpenAPI document and want one tool per operation41 tools here, 24 of them writes, until x-mcp filtering trims themThe agent should only read, with a short tool list
Swagger CodegenYour team generates typed clients for the same API with itNo MCP target among its languages, so it leaves the server to youYou need the server, not the client
Voxgig SDK Catalog Go MCP serverA catalog entry exists for the API and two read-only tools sufficeUnofficial, built from source at a pinned commit, and its list results need a shim for the official clientsThe vendor ships a server, or the agent must write

Voxgig maintains the SDK Catalog and is the subject here. The catalog’s README calls its SDK unofficial and unaffiliated with the API provider.

The official server tracks its API, and costs a sign-in or a token whose permissions you must trim. openapi-mcp-generator covers whatever the document covers, writes included. The catalog server covers less and reads only. Swagger Codegen and Kiota write clients, so a team on either connects one of the other three.

Pin the server to one commit

The repository’s go-mcp/go.mod points the SDK at a sibling directory, so go install ...@v0.0.7 fails. A consumer module of your own names the server with a tool directive and replaces the SDK with the same commit of main, as a pseudo-version.1

module example.com/connect-jsonplaceholder

go 1.25.0

// The catalog's MCP server for JSONPlaceholder, built with
// go build -o bin/jsonplaceholder-mcp github.com/voxgig-sdk/jsonplaceholder-sdk/go-mcp
tool github.com/voxgig-sdk/jsonplaceholder-sdk/go-mcp

// Its own go.mod points the SDK at a sibling directory. This names the SDK at
// the same commit of main instead, because the newest go/ tag lists no posts.
replace github.com/voxgig-sdk/jsonplaceholder-sdk/go => github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261103055737-a21ce5a97d8e
go build -o bin/jsonplaceholder-mcp github.com/voxgig-sdk/jsonplaceholder-sdk/go-mcp && ls bin
jsonplaceholder-mcp

List the tools and call a known endpoint

connect.mjs starts the binary over stdio, the way an MCP client does, with JSONPLACEHOLDER_BASE pointing at standin.mjs on 127.0.0.1. The stand-in copies its routes from the catalog’s own OpenAPI document and its records from the live API. It answers GET only.

node connect.mjs
server jsonplaceholder 0.0.1, protocol 2025-06-18
tools
  jsonplaceholder_list  readOnlyHint true  args entity, query?
  jsonplaceholder_load  readOnlyHint true  args entity, query
entity enum  album, comment, photo, post, todo, user
document     albums, comments, photos, posts, todos, users  one entity per collection
jsonplaceholder_load {"entity":"post","query":{"id":1}}
  the API was asked: GET /posts/1
  structuredContent: an object, every field the document declares for Post, with its type
jsonplaceholder_load {"entity":"post","query":{"id":9999}}
  the API was asked: GET /posts/9999
  isError: JsonplaceholderSDK: load: request: 404: Not Found
jsonplaceholder_list {"entity":"post","query":{"userId":1}}
  the API was asked: GET /posts?userId=1
  structuredContent: an array of 10 records, where protocol 2025-06-18 asks for an object

Two tools, not one per operation. Each takes an entity and a query map, and the check compares the entity list with the document’s collections. A missing post is a tool error, not a crash. A client configuration needs the same three things the script passes: the binary path, -transport stdio, and the base URL variable.

Check when it was generated

The server reports version 0.0.1, a constant in its main.go, and the repository’s .sdk/log/generated.jsonl holds a time and a file list but no tool versions. The commit message names them. record.sh read it:

main a21ce5a97d8ed4c85e02123b61a67a3a408d60a9 2026-11-03T05:57:37+00:00
main subject: Regenerate on sdkgen 4.38.0 and apidef 8.27.0
@voxgig/sdkgen 4.38.0 registry
@voxgig/apidef 8.27.0 registry
go-mcp/v0.0.7 cbc0971e5f5cf18e911de8bee1cd90ed68af8182 2026-08-13T18:47:57+00:00

A test holds the pseudo-version in go.mod to that commit hash and time. The same script ran the server once against the live API, on its own default base URL:

recorded 2026-11-22
the server's default base URL, against https://jsonplaceholder.typicode.com
  load post 1: equals GET /posts/1 true
  load post 1 against the document's Post: every field, with its type
  list post: an array of 100; GET /posts returns 100
  load post 9999: isError true, JsonplaceholderSDK: load: request: 404: Not Found

Drift shows up there first. A field the API added, or a route it moved, fails that comparison before an agent meets it.

Get a server when your SDK comes from Swagger Codegen or Kiota

Neither generator writes an MCP server. generate.sh recorded Swagger Codegen 3.0.85’s langs list, which has no MCP target, and Kiota 1.39.0’s commands and its nine --language values, none of them a server. Kiota’s command reference names no MCP command either. A team on either keeps its generated client for its own code and connects a ready-made server for the agent: the vendor’s, the catalog’s, or one generated from the document.

The third route is openapi-mcp-generator. generate.sh ran 5.0.1 on the catalog’s document, installed and built the server it wrote, and listed its tools against the same stand-in:

tools: 41, readOnlyHint 17, the rest 24

It answered the same GET /posts/1, and the tools it marks as writes include createPost and deletePost.2 Its server pulls @modelcontextprotocol/server by a caret range, so two installs a month apart can differ. Its README documents an x-mcp extension and --default-include false for trimming the list.

Swagger Codegen suits a team that wants server stubs beside its clients, since its list includes go-server, spring and nodejs-server. Kiota suits one that must find the API’s description first, because its commands include search and download.

Keep the HTTP transport away from browsers

The server accepts a request that names a foreign Origin. origin.mjs starts it with -transport http on 127.0.0.1, once as built and once with the Go SDK’s compatibility switch:

node origin.mjs
initialize over -transport http on 127.0.0.1, as built
  no Origin header                  200
  Origin: https://attacker.example  200
  Host: attacker.example            403
initialize over -transport http on 127.0.0.1, with MCPGODEBUG=enableoriginverification=1
  no Origin header                  200
  Origin: https://attacker.example  403
  Host: attacker.example            403

The transport specification says servers “MUST validate the Origin header”. Go SDK v1.6.0 refuses a foreign Host only on a connection that arrives on a loopback address, and checks Origin only when the server configures it, at line 261 of streamable.go. The catalog server configures nothing and listens on :8080, every interface, at line 17 of its main.go.

Run it over stdio. If a browser can reach it over HTTP, pass -addr 127.0.0.1:<port> and set the switch above. The switch is a v1.6.0 compatibility setting that v1.8.0 no longer reads, so it holds only while go.sum pins v1.6.0.

Check it worked

The suite builds the server if bin/ is empty, then runs every check on this page against the stand-in, the shim below included. One test sends an id of ../users/1 and requires GET /posts/..%2Fusers%2F1, so the id stays one path segment.

node --test connect.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 3176.692073

When it goes wrong

The agent’s list call fails with expected record, received array. The server returns the list as the tool’s output value at line 99 of tools.go, and Go SDK v1.6.0 copies any output value into structuredContent unchecked, at line 384 of server.go. Both official TypeScript clients, 2.4.0 and 1.32.2, negotiate protocol 2025-11-25 with it, and that revision returns structured content “as a JSON object”, as 2025-06-18 does. The 2026-07-28 revision allows any JSON value, but neither client offers it.

record.sh ran both clients on this build, on go-mcp/v0.0.7, and on this build behind wrap-list.mjs:

grep -E '^build|_list' record/clients.txt
build main
  @modelcontextprotocol/client jsonplaceholder_list (asked GET /posts?userId=1): refused the result (structuredContent: expected record, received array)
  @modelcontextprotocol/client jsonplaceholder_list (asked GET /posts): refused the result (structuredContent: expected record, received array)
  @modelcontextprotocol/sdk jsonplaceholder_list (asked GET /posts?userId=1): refused the result (structuredContent: expected record, received array)
  @modelcontextprotocol/sdk jsonplaceholder_list (asked GET /posts): refused the result (structuredContent: expected record, received array)
build tag
  @modelcontextprotocol/client jsonplaceholder_list (asked GET /users/%7Buser_id%7D/posts?userId=1): refused the result (structuredContent: expected record, received array)
  @modelcontextprotocol/client jsonplaceholder_list (asked GET /users/%7Buser_id%7D/posts): refused the result (structuredContent: expected record, received array)
  @modelcontextprotocol/sdk jsonplaceholder_list (asked GET /users/%7Buser_id%7D/posts?userId=1): refused the result (structuredContent: expected record, received array)
  @modelcontextprotocol/sdk jsonplaceholder_list (asked GET /users/%7Buser_id%7D/posts): refused the result (structuredContent: expected record, received array)
build main, behind wrap-list.mjs
  @modelcontextprotocol/client jsonplaceholder_list (asked GET /posts?userId=1): accepted, a result, structuredContent.items of 10
  @modelcontextprotocol/client jsonplaceholder_list (asked GET /posts): accepted, a result, structuredContent.items of 10
  @modelcontextprotocol/sdk jsonplaceholder_list (asked GET /posts?userId=1): accepted, a result, structuredContent.items of 10
  @modelcontextprotocol/sdk jsonplaceholder_list (asked GET /posts): accepted, a result, structuredContent.items of 10

Put wrap-list.mjs between the client and the server. It moves a structuredContent that is not an object under items and passes every other line through, so the client runs node wrap-list.mjs bin/jsonplaceholder-mcp -transport stdio. A test checks that the tool list, the load result and the text content come through unchanged.

When not to do this

Do not connect the catalog server where the vendor ships its own. GitHub publishes its server in its own organization, with toolsets and a --read-only flag. The catalog server is only as current as the document it was generated from, at the commit you pinned.

Do not take @latest for the newest server. The go-mcp/v0.0.7 tag predates main by almost three months, and its post list asks for /users/%7Buser_id%7D/posts.

Skip the Voxgig SDK Catalog when the agent must write. Its server has no write tools unless the SDK’s own model file turns them on, and openapi-mcp-generator covers every operation the document has. Kiota or Swagger Codegen is the better fit when your own code calls the API: a typed client lets the compiler check each call, which an MCP tool list cannot do.

Last verified

Verified 2026-11-22 against Node 22.23.5 and Go 1.25.0, with the catalog’s go-mcp at commit a21ce5a and the Go MCP SDK v1.6.0. openapi-mcp-generator 5.0.1, Kiota 1.39.0 and Swagger Codegen 3.0.85 ran once, in generate.sh, and the live API and the official TypeScript clients once, in record.sh. Kiota ran only to print its version and help. The GitHub MCP Server was read from its README and not run, because it needs a GitHub sign-in or token.

Footnotes

  1. The Go modules reference builds a pseudo-version from the last release tag by adding one to the patch number, so v0.0.8-0.20261103055737-a21ce5a97d8e names a release after v0.0.7 that nobody has tagged. The middle part is the commit time in UTC, to the second, and the last is the first twelve characters of the commit hash. ↩︎ Back to text

  2. JSONPlaceholder’s guide is candid about its writes. A POST answers with "id": 101, and “the resource is not really created on the server, but the response is faked as if”. The guide says the same of updates, patches and deletes. By its account, a call to any of the 24 write tools in that listing would get a faked answer, which no run here tested. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.