POST
/
v1
/
teams
/
{teamId}
/
agent-mcp-servers
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.agentMcpServers.createAgentMcpServer({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  body: {},
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "slug": "<string>",
  "url": "<string>",
  "transport": "streamable_http",
  "hasCredentials": true,
  "tokenExpiresAt": "<string>",
  "toolAllowlist": [
    "<string>"
  ],
  "toolNames": [
    "<string>"
  ],
  "lastError": "<string>",
  "needsReauth": true,
  "lastTestedAt": "<string>",
  "createdBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

Body

application/json
​
name
string
required

Display name, unique within the team (1-80 characters). Its slug prefixes the proxied tool names as mcp____.

Required string length: 1 - 80
​
url
string
required

The server's streamable HTTP endpoint. Must be https and resolve to a public address; private, loopback and link-local hosts are rejected with 400.

Required string length: 1 - 2048
Example:

"https://mcp.example.com/mcp"

​
authKind
enum<string>
required

none: no credentials. bearer: a static token you supply. oauth: authorize through the server's OAuth flow (start via the oauth/start endpoint).

Available options:
none,
bearer,
oauth
​
bearerToken
string

Static bearer token for authKind bearer. Stored encrypted and never returned by any endpoint.

Required string length: 1 - 4096
​
toolAllowlist
string[]

Remote tool names the agent may use from this server. Empty means every tool the server lists.

Maximum array length: 200

a string at most 200 character(s) long

Required string length: 1 - 200

Response

Success

​
id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
name
string
required

Display name, unique within the team (1-80 characters). Its slug prefixes the proxied tool names as mcp____.

Required string length: 1 - 80
​
slug
string
required

The lower-case slug of the name, unique within the team; it prefixes the proxied tool names as mcp____. Two names that slug the same cannot coexist.

​
url
string
required

The server's streamable HTTP endpoint. Must be https and resolve to a public address; private, loopback and link-local hosts are rejected with 400.

Required string length: 1 - 2048
Example:

"https://mcp.example.com/mcp"

​
transport
enum<string>
required

Wire transport; only streamable_http is supported.

Available options:
streamable_http
​
authKind
enum<string>
required

none: no credentials. bearer: a static token you supply. oauth: authorize through the server's OAuth flow (start via the oauth/start endpoint).

Available options:
none,
bearer,
oauth
​
hasCredentials
boolean
required

Whether credentials are stored for the server (a bearer token, or OAuth tokens after a completed authorization). The credentials themselves are never returned.

​
tokenExpiresAt
string | null
required

When the stored OAuth access token expires (ISO-8601 UTC); null for no expiry or no OAuth tokens. The worker refreshes tokens expiring within 15 minutes.

​
toolAllowlist
string[]
required

Remote tool names the agent may use from this server. Empty means every tool the server lists.

Maximum array length: 200

a string at most 200 character(s) long

Required string length: 1 - 200
​
toolNames
string[]
required

The tool names the server listed on its last successful test or connection.

​
lastError
string | null
required

The last connection, authorization or refresh failure; null when the last attempt succeeded.

​
needsReauth
boolean
required

True once the stored OAuth grant could not be refreshed after repeated attempts: the server is skipped by managed runs until it is connected again.

​
lastTestedAt
string | null
required

When the server was last tested (ISO-8601 UTC).

​
createdBy
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
createdAt
string
required

When the server was added (ISO-8601 UTC).

​
updatedAt
string
required

When the server last changed (ISO-8601 UTC).