# 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.

Source: https://voxgig.com/howto/connect-a-generated-mcp-server-for-an-api

- Audience: api-consumer
- Level: intermediate
- Languages: go
- Verified: 2026-11-22
- Published: 2026-11-22

## 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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [GitHub MCP Server](https://github.com/github/github-mcp-server) | The vendor publishes and supports its own server, as GitHub does | A GitHub sign-in or token with the permissions you grant, and toolsets to trim | The vendor has no server, or you need offline tests |
| [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/overview) | Your team already generates its clients with Kiota | Writes no MCP server, so you connect a ready-made one or write a facade | You want one command that yields a server |
| [openapi-mcp-generator](https://github.com/harsha-iiiv/openapi-mcp-generator) | You hold the API's OpenAPI document and want one tool per operation | 41 tools here, 24 of them writes, until `x-mcp` filtering trims them | The agent should only read, with a short tool list |
| [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) | Your team generates typed clients for the same API with it | No MCP target among its languages, so it leaves the server to you | You need the server, not the client |
| [Voxgig SDK Catalog Go MCP server](https://github.com/voxgig-sdk/jsonplaceholder-sdk) | A catalog entry exists for the API and two read-only tools suffice | Unofficial, built from source at a pinned commit, and its list results need a shim for the official clients | The 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](https://go.dev/ref/mod#go-mod-file-tool) and replaces the SDK with the same
commit of `main`, as a [pseudo-version](https://go.dev/ref/mod#pseudo-versions).[^1]

```go title="go.mod"
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
```

```bash
go build -o bin/jsonplaceholder-mcp github.com/voxgig-sdk/jsonplaceholder-sdk/go-mcp && ls bin
```

```text output
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.

```bash
node connect.mjs
```

```text output
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:

```text title="record/commit.txt"
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:

```text title="record/live-call.txt"
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](https://learn.microsoft.com/en-us/openapi/kiota/using)
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:

```text title="generated/openapi-mcp-generator.txt"
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:

```bash
node origin.mjs
```

```text output
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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#security-warning)
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`](https://github.com/modelcontextprotocol/go-sdk/blob/v1.6.0/mcp/streamable.go#L261).
The catalog server configures nothing and listens on `:8080`, every interface, at
[line 17 of its `main.go`](https://github.com/voxgig-sdk/jsonplaceholder-sdk/blob/a21ce5a97d8ed4c85e02123b61a67a3a408d60a9/go-mcp/main.go#L17).

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.

```bash
node --test connect.test.mjs
```

```text output
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`](https://github.com/voxgig-sdk/jsonplaceholder-sdk/blob/a21ce5a97d8ed4c85e02123b61a67a3a408d60a9/go-mcp/tools.go#L99),
and Go SDK v1.6.0 copies any output value into `structuredContent` unchecked, at
[line 384 of `server.go`](https://github.com/modelcontextprotocol/go-sdk/blob/v1.6.0/mcp/server.go#L384).
Both official TypeScript clients, 2.4.0 and 1.32.2, negotiate protocol 2025-11-25 with it, and
[that revision](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content)
returns structured content "as a JSON object", as 2025-06-18 does. The
[2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#structured-content)
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`:

```bash
grep -E '^build|_list' record/clients.txt
```

```text output
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.

## Related how-tos

- [Add a stdio MCP server to Claude Code](/howto/add-a-stdio-mcp-server-to-claude-code)

- [Choose between calling an SDK directly and using MCP](/howto/direct-sdk-calls-versus-mcp-in-an-agent)

- [Let a coding agent probe a live API through an MCP server](/howto/probe-live-api-responses-through-an-mcp-server)

- [Decide whether to generate or hand-write an MCP server](/howto/generate-or-hand-write-an-mcp-server)

- [Health check your MCP server connections](/howto/health-check-mcp-server-connections)

## 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.

[^1]: The [Go modules reference](https://go.dev/ref/mod#pseudo-versions) 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.

[^2]: JSONPlaceholder's [guide](https://jsonplaceholder.typicode.com/#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.