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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| 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 | 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 | 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 | 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 | 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 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.
Related how-tos
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
-
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-a21ce5a97d8enames a release afterv0.0.7that 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 -
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