Wire SDK

For teams building agents, harnesses, or AI infrastructure who want Wire container connectivity as a first-class part of the product. Your user authorizes in their browser; you get back a scoped MCP endpoint and API key to hand to your agent.

You don’t run the storage. You don’t build the import flow. You don’t manage user data. Wire owns the connect screen, the auth, and the connection lifecycle. Your agent keeps speaking MCP, now with whatever the user has brought along.

This page covers connect mode, where each user authorizes against their own Wire account. If your product should own the containers and the billing instead, with no end-user Wire account at all, see Provision mode.

Note

New here? Read Agents first for the primitive this SDK is built around.

Install

TypeScript

npm install @usewire/sdk

Runs on Node 18+, Cloudflare Workers, Deno, and Bun.

Register your agent

Before the SDK can connect on behalf of your users, register your agent from the Agents entry in your account menu in the Wire dashboard. You’ll get a slug (passed as agentId) that the SDK uses to identify your agent on every call.

By creating an agent you agree to the Wire developer terms, which cover how your agent may use what a user shares with it.

Agent icon

Your agent’s icon is the image people see next to its name on the consent screen and in their container’s connections. Set it on your agent record:

curl -X PATCH https://app.usewire.io/api/v1/agents/my-agent \
  -H 'content-type: application/json' --cookie "$WIRE_SESSION" \
  -d '{ "icon": "https://my-agent.example/icon-256.png" }'

• It must be an https URL of at most 512 characters, with no credentials or #fragment in it, on a public host (not localhost, a private address, or a Wire domain). Send "icon": null to remove it.
• It must be a raster image: PNG, JPEG, WebP, GIF, or ICO, at most 256 KB. SVG is not accepted. A square 256×256 PNG is recommended. Wire follows at most two redirects, and each one must meet the same URL rules.
• Wire fetches the image and serves it itself, so your users’ browsers never contact your host when they see your icon. Wire keeps a copy for up to a day; changing the URL shows the new image right away.
• If the image can’t be fetched or isn’t a supported type, Wire shows your agent’s initials instead.

The connect answers the SDK reads (agent_icon) carry the URL Wire serves the icon from, not the one you registered.

Connect

TypeScript

import { WireClient } from '@usewire/sdk';

const client = new WireClient({ agentId: 'my-agent' });

const connection = await client.connect({ label: 'my-laptop' });

// Hand these to your agent's MCP client:
const mcp = new MCPClient({
  url: connection.mcpUrl,
  headers: { 'x-api-key': connection.apiKey },
});

connect() shows the user a short code and opens their browser. The user types the code on the connect screen, picks a container, and connect() resolves with the result. That’s the whole happy path.

What you get

TypeScript

interface Connection {
  mcpUrl: string;
  apiUrl: string;
  apiKey: string;
  containerId: string;
  containerName: string;
  orgSlug: string | null;
  expiresAt: Date | null;   // ephemeral containers only
  agentId: string;
  credentialId: string;
  deviceKey: DeviceKey;
  connectedAt: Date;
  label?: string;
}

The SDK persists nothing. Keep whatever fields you want from the result, however you want. For typical agent use, the only fields you need at runtime are mcpUrl and apiKey.

Disconnect and status

TypeScript

await client.disconnect(connection.apiKey);
await client.getStatus(connection.apiKey);

disconnect revokes the apiKey but keeps the install identity, so reconnect from the same deviceKey still works. getStatus returns a live snapshot of the container and connection.

Go deeper

Connect flows Custom prompts, reusing the install identity, and non-blocking connects for turn-based agents.

Sign in with Wire Let people sign in to your own app with their Wire account, and call your agent's tools as them from your server.

Ephemeral containers and claim No-account onboarding: connect first, let the user try Wire, then upgrade their container in-flow.

Provision mode No end-user account at all: your backend creates containers in your own org with an API key, and you own the billing.

Skills and instructions Tell every agent that uses your agent's container how to use it: short instructions on connect, and a full skill loaded on demand.

Reference Every method, type, and error code in one place.