SDKs
SDKs
The SDK family: which languages are available, how to install them, and what every SDK does the same way.
An SDK is how your own service becomes an agent: a small library that connects out to the gateway, registers the tools, resources and prompts you define, and runs your handlers when an MCP client calls them. You write ordinary functions in your own language; the SDK handles the connection, the protocol and the reconnects.
The Node.js and Go SDKs are available now. The Python, Java, C#, Rust and PHP SDKs are coming soon.
Languages
| Language | Status | Package | Install |
|---|---|---|---|
| Node.js | Available | @spacefix/core, plus @spacefix/telemetry for dashboard process metrics | npm install @spacefix/core and, optionally, npm install @spacefix/telemetry |
| Go | Available | github.com/softmode/spacefix-go, plus the separate OpenTelemetry module github.com/softmode/spacefix-go/otel | go get github.com/softmode/spacefix-go and, optionally, go get github.com/softmode/spacefix-go/otel |
| Python | Coming soon | svc-sdk | pip install svc-sdk |
| Java | Coming soon | io.spacefix:sdk | Maven or Gradle dependency |
| C# | Coming soon | Spacefix.Sdk | dotnet add package Spacefix.Sdk |
| Rust | Coming soon | svc-sdk | cargo add svc-sdk |
| PHP | Coming soon | spacefix/sdk | composer require spacefix/sdk |
The pages for unreleased languages show a clearly marked preview of the planned API. It is a preview only: nothing on those pages can be installed yet, and the API may change before release.
What every SDK does the same way
- Connects out. Your process opens one outbound HTTPS connection to the gateway and keeps it open. There is no public endpoint to host, no inbound port and no tunnel. Calls arrive down that connection, and results go back as ordinary HTTPS requests.
- Registers tools, resources and prompts. A tool is a function the model calls with arguments. A resource is data a client reads by URI. A prompt is a message template a user picks from a client's menu. The gateway holds their names, descriptions and JSON Schemas, never your code.
- Runs your handlers. Handlers run in your process, with your database and your secrets. A returned value becomes the tool's result; a thrown error becomes an error result the model can read.
- Reconnects with backoff. If the connection drops, the agent reconnects by itself, waiting 1 s, 2 s, 4 s ... up to 30 s between attempts, and starts again from 1 s once a connection is accepted.
- Reports telemetry. Optionally, the agent reports its process health (memory, CPU, event loop or scheduler delay, call counts) to the Agents page of your project.
- Speaks OpenTelemetry. Optionally, each call becomes a span in your own tracing backend, continuing the MCP client's trace, with duration metrics and connection logs. Argument values and results are never recorded.
- Needs an always-on process. The connection is long-lived, so an agent runs in a container, a VM or a worker, not in request-scoped serverless.
- Spreads across replicas. Every copy of your service opens its own connection and the gateway spreads calls across them, so keep state in a database, not in process memory. See Running more than one copy.
You need a project and an agent key (or a full key) from the dashboard to connect. See Keys.
Feature comparison
| Node.js | Go | |
|---|---|---|
| Status | Available (1.0.0) | Available (0.1.0) |
| Language version | Node.js 20 or newer | Go 1.22 or newer (the OpenTelemetry module needs Go 1.26) |
| Runtime dependencies | None | None (core module) |
| How you describe arguments | Zod or another Standard Schema library, or plain JSON Schema | A Go struct with tags, or a raw JSON Schema |
| Resources and prompts | Yes | Yes |
| Several tools from one file or package | defineTool, register | One AddTool call per tool |
| Register after connecting | Not advertised until the next reconnect | Refused (ErrFrozen) |
Reconnect with backoff, jitter and Retry-After | Yes | Yes |
| Retry a failed result post | Yes | Yes |
| Give up on a bad key | fatalStatuses option | StopOnPermanentError option |
| Detect a silent connection | No | Yes (90 s without data by default) |
| Cancel a handler when its answer is no longer wanted | No | Yes (context.Context) |
| Graceful shutdown waits for running calls | Yes, 5 s by default | Yes, 10 s by default |
| Concurrency | Event loop; async handlers interleave | A goroutine per call; optional MaxConcurrency |
| Dashboard process metrics | @spacefix/telemetry | spacefix-go/telemetry |
| OpenTelemetry | Built in; on when @opentelemetry/api is installed | An adapter module, go/otel |
Both SDKs speak the same protocol, show up the same way on the Agents page, and produce the same span and metric names, so you can run agents in different languages in the same project.
How to choose
- Use the language your service already uses. The point of an SDK is to call the code you already have. If your service is TypeScript or JavaScript, use the Node.js SDK; if it is Go, use the Go SDK.
- Writing a new agent with no existing service? Either works. The Node.js SDK is the shorter path if you already have a schema library like Zod; the Go SDK gives you schemas generated from structs, cancellation through
context.Contextand a fake gateway for tests. - Your language is Python, Java, C#, Rust or PHP? The SDK is coming. In the meantime, use the Node.js or Go SDK, or the agent protocol directly (below).
- Serverless API? Run the agent as a separate always-on worker that shares your service layer.
No SDK for your language yet?
An agent is a handful of HTTPS calls: one request that registers your tools and opens an event stream, and one request per result. Any language with an HTTP client can do it, and the protocol is documented in full in The agent protocol. The SDKs are a convenience over it: reconnects, backoff, schemas and telemetry are things you would otherwise write yourself.
Next steps
- Quickstart: from a new account to your first successful call
- Node.js SDK
- Go SDK
- The agent protocol