Skip to main content
POST
Create MCP server

Restrictions

Usage

  • command/args/env apply to stdio; url/headers apply to sse/streamable-http.
  • server_name must start with a letter and contain only letters, digits, -, or _, and must be unique within its scope (account-wide or one team); violations return InvalidParameter.
  • Without source_template_name, creating into a team (team_id > 0) requires the caller to belong to that team, and only the account owner or an admin may create at account scope (team_id=0).
  • Setting source_template_name installs a marketplace template: the template must exist (ResourceNotFound otherwise), team_id is ignored and the server is created at account scope, and the connection fields must equal the template’s own except for its declared parameter values. Templates with per-user auth whose parameters let the installer choose the destination host can be installed only by the account owner or an admin.
  • Each environments entry must be cloud or the ID of a BYOC runner that is account-scoped or belongs to one of the caller’s teams; duplicates are dropped and an empty string is rejected. Omitted or empty means all environments.
  • per_user_secret auth mode requires secret_schema to be valid JSON with a non-empty header_name.
  • env and headers values are masked when the key name contains KEY, SECRET, TOKEN, PASSWORD, PASSWD, CREDENTIAL, or AUTHORIZATION (case-insensitive), or has a PWD / PASS segment, or the value is encrypted at rest; such values are also encrypted at rest.
  • The response is the stored server. Its tool list is then fetched in the background through an already-online execution environment; the call does not wait for it.
  • Every call is recorded in the account audit log.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Configuration for a new MCP server.

server_name
string
required

MCP server name: must start with a letter and contain only letters, digits, -, or _ (@ is reserved); unique within its scope (account-wide or one team).

Required string length: 1 - 255
description
string
required

Server description.

Required string length: 1 - 1024
transport
enum<string>
required

Transport protocol: stdio launches a local process via command/args/env, sse / streamable-http connects to a remote service via url/headers.

Available options:
stdio,
sse,
streamable-http
command
string

Executable command (stdio transport).

args
string[]

Command arguments (stdio transport).

env
object

Environment variables (stdio transport). Values under credential-looking names (containing KEY, SECRET, TOKEN, PASSWORD, …) are encrypted at rest and masked in responses.

url
string

Server URL (sse / streamable-http transport).

headers
object

HTTP headers (sse / streamable-http transport). Values under credential-looking names (containing KEY, TOKEN, AUTHORIZATION, …) are encrypted at rest and masked in responses.

connect_timeout
integer

Connection timeout in seconds. Omitted or 0 is stored as 0 and means the 10-second default.

call_timeout
integer

Tool-call timeout in seconds. Omitted or 0 is stored as 0 and means the 60-second default.

auth_mode
enum<string>
default:shared

Who supplies the credential:

  • shared (default; an empty value behaves the same): one credential stored on the server (env / headers) is used for every caller.
  • per_user_secret: each user stores their own secret, sent in the header named by secret_schema.header_name.
  • per_user_oauth: each user completes their own OAuth authorization; discovery and client registration run on first use.

per_user_secret requires secret_schema with a non-empty header_name; any other value returns InvalidParameter.

Available options:
shared,
per_user_secret,
per_user_oauth
secret_schema
string

JSON secret schema; required when auth_mode=per_user_secret.

oauth_metadata
string

JSON OAuth metadata; reserved for per_user_oauth.

status
enum<string>
default:enabled

Initial status: enabled (default) or disabled (created but kept off).

Available options:
enabled,
disabled
team_id
integer<int64>

Team scope: 0 = account-wide (account owner or admin only); >0 = a team the caller belongs to. Ignored when source_template_name is set — marketplace installs are always account-wide.

environments
string[]

Execution environments this server is callable from: cloud and/or BYOC runner environment IDs. Omitted or empty means all environments.

allow_insecure_oauth_http
boolean

Allow this server's OAuth token exchange over plaintext HTTP. Testing use only; defaults to false.

allow_insecure_tls_skip_verify
boolean

Skip TLS certificate verification when connecting to this server. Testing use only; defaults to false.

source_template_name
string

Name of the marketplace template to install. When set, the template must exist, the server is created at account scope, and the connection fields must match the template except for its declared parameter values. Cannot be changed later.

Response

Success

Standard response envelope used by every Flashduty public API. On success data contains the endpoint-specific payload and error is absent. On failure error is present and data is absent. request_id is always present and is also mirrored in the Flashcat-Request-Id response header.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

error
object

Error payload inside the response envelope. Present only on non-2xx responses.

data
object

An MCP server (connector) registered on the account.