Create a connector

POST/v1/mcp-integrations

Create a connector.

Registers an upstream for the MCP Gateway: an MCP server (kind: MCP, the default), a REST API described by an OpenAPI document (OPENAPI) or a REST API with hand-declared endpoints (HTTP). Credentials (headers, query parameters, OAuth client secret) are stored encrypted and never returned. The URL, spec URL and token endpoint must pass the egress policy (public addresses only). The connector starts with sync_status: NEVER: sync it to discover its capabilities. Without workspace_id it is an organization-level connector that can be shared with workspaces.

Requires an organization admin key, or a workspace admin key for workspace_id (an organization-level connector needs an organization admin). Returns 400 when the settings do not fit together (for example headers with an OAuth auth type, a spec on an MCP connector, an unknown guardrail). Returns 402 when the organization's plan does not include the MCP Gateway.

Authorization

AuthorizationBearer va_
A platform API key (va_...), created under Settings > API keys. Scoped to an organization or one workspace, with an admin or member role. Used by the management API.

Request body application/json

the connector to create

organizationstringrequired
The organization's identifier (slug).
At least 1 characters
namestringrequired
Display name, up to 255 characters.
At least 0 characters · At most 255 characters
urlstringrequired
The upstream URL, up to 2048 characters: the MCP server's endpoint for MCP, the API's base URL for OPENAPI and HTTP (no query string or fragment). It must pass the gateway's egress policy (public addresses only).
At least 0 characters · At most 2048 characters
workspace_idstring<uuid>
The workspace that owns the connector (UUID). Absent: an organization-level connector, which can be shared with several workspaces (see global_workspace_access and the workspace access endpoint).
descriptionstring
Optional free-text description.
transportenum<string>
The upstream transport. Only HTTP (Streamable HTTP); the default.
One of "HTTP"
auth_typeenum<string>
How the gateway authenticates upstream: NONE, HEADERS, OAUTH_AUTO or OAUTH_CLIENT_CREDENTIALS. Default: HEADERS when headers or query_params are given, else NONE.
One of "NONE", "HEADERS", "OAUTH_AUTO", "OAUTH_CLIENT_CREDENTIALS"
headersmap<string, string>
HEADERS auth: header name to value, sent on every upstream request. Write-only. Names that the gateway sets itself (for example Host, Content-Type, Mcp-Session-Id) are refused, and values may not contain control characters. Cannot be combined with an OAuth auth type.
oauthobject
OAuth settings for a connector that authenticates upstream with OAuth. OAUTH_CLIENT_CREDENTIALS needs client_id and client_secret: a client you registered at the upstream's authorization server. For OAUTH_AUTO on an MCP server they are optional: without a client the gateway registers itself; give one when the upstream requires pre-registration. On an OPENAPI or HTTP connector, OAuth needs token_endpoint, and OAUTH_AUTO also needs authorization_endpoint and client_id.
Child attributes
- client_idstring
  The OAuth client ID, up to 500 characters.
  At least 0 characters · At most 500 characters
- client_secretstringwrite-only
  The client secret, up to 2000 characters. Write-only: stored encrypted, never returned.
  At least 0 characters · At most 2000 characters
- scopesstring
  Scopes to request, space-separated, up to 1000 characters. Empty clears them.
  At least 0 characters · At most 1000 characters
- token_endpointstring
  The upstream token endpoint, up to 2000 characters. On an MCP server it skips discovery for client credentials. It must pass the egress policy.
  At least 0 characters · At most 2000 characters
- authorization_endpointstring
  OAUTH_AUTO on an OPENAPI or HTTP connector: where people sign in (an https URL, up to 2000 characters). An MCP server's is discovered, so it is refused there.
  At least 0 characters · At most 2000 characters
kindenum<string>
What is behind the connector: MCP (default), OPENAPI or HTTP. Fixed once created.
One of "MCP", "OPENAPI", "HTTP"
spec_urlstring
OPENAPI only: where the OpenAPI document is fetched from, on every sync. Give this or spec_content. Up to 2048 characters.
At least 0 characters · At most 2048 characters
spec_contentstring
OPENAPI only: the OpenAPI 3.0 or 3.1 document itself, in the format spec_format names.
spec_formatenum<string>
OPENAPI only: the format of spec_content, JSON or YAML. Required with spec_content.
One of "JSON", "YAML"
http_toolsobject[]
HTTP only: the endpoints, declared by hand. At most 200.
At most 200 items
Child attributes
- namestringrequired
  The tool's name, up to 128 characters.
  At least 0 characters · At most 128 characters
- methodstringrequired
  The HTTP method: GET, POST, PUT, PATCH, DELETE or HEAD.
  At least 1 characters
- pathstringrequired
  The path, relative to the connector's base URL, up to 2048 characters. May hold {name} placeholders filled from arguments.
  At least 0 characters · At most 2048 characters
- titlestring
  Human-readable title, up to 255 characters.
  At least 0 characters · At most 255 characters
- descriptionstring
  What the tool does, up to 4000 characters. Agents read it to choose the tool.
  At least 0 characters · At most 4000 characters
- querystring[]
  Arguments sent as query parameters.
- headersstring[]
  Arguments sent as request headers.
- input_schemamap<string, object>
  A JSON Schema of type object; its properties are the tool's arguments.
- body_formatstring
  How the body is encoded: json (default) or form.
query_paramsmap<string, string>
OPENAPI and HTTP with HEADERS auth: API keys sent as query parameters (name to value), alone or with headers. Write-only.
global_workspace_accessboolean
Organization-level connectors only: true lets every workspace in the organization use it. Default false. Ignored for a workspace-owned connector.
org_connection_for_usersboolean
OAUTH_AUTO only: true lets a signed-in person who has not connected their own account use the organization connection. Default false. Agents on an MCP key always use the organization connection.
guardrail_slugsstring[]
Guardrails run on every call through this connector, in order, at most 10: INPUT checks on the arguments sent upstream, OUTPUT checks on what the upstream returns. Each must exist in the organization; an organization-level connector takes only organization-level guardrails.
At most 10 items

Responses

201application/json

Created

idstring<uuid>
The connector's ID (UUID).
slugstring
The connector's slug (mcpi- followed by 16 characters), used in the API paths.
organizationstring
The organization that owns it.
workspace_idstring<uuid>
The owning workspace (UUID). Absent for an organization-level connector.
namestring
Display name.
descriptionstring
Description.
urlstring
The upstream URL (the base URL for a REST connector).
kindenum<string>
MCP, OPENAPI or HTTP.
One of "MCP", "OPENAPI", "HTTP"
spec_urlstring
OPENAPI: where the document is fetched from.
has_spec_documentboolean
OPENAPI and HTTP: whether an uploaded document is stored. The document itself is not returned.
spec_formatenum<string>
OPENAPI: the format of the uploaded document, JSON or YAML.
One of "JSON", "YAML"
spec_hashstring
OPENAPI and HTTP: SHA-256 of the spec the last sync read.
http_toolsobject[]
HTTP: the declared endpoints.
Child attributes
- namestringrequired
  The tool's name, up to 128 characters.
  At least 0 characters · At most 128 characters
- methodstringrequired
  The HTTP method: GET, POST, PUT, PATCH, DELETE or HEAD.
  At least 1 characters
- pathstringrequired
  The path, relative to the connector's base URL, up to 2048 characters. May hold {name} placeholders filled from arguments.
  At least 0 characters · At most 2048 characters
- titlestring
  Human-readable title, up to 255 characters.
  At least 0 characters · At most 255 characters
- descriptionstring
  What the tool does, up to 4000 characters. Agents read it to choose the tool.
  At least 0 characters · At most 4000 characters
- querystring[]
  Arguments sent as query parameters.
- headersstring[]
  Arguments sent as request headers.
- input_schemamap<string, object>
  A JSON Schema of type object; its properties are the tool's arguments.
- body_formatstring
  How the body is encoded: json (default) or form.
query_param_namesstring[]
Names of the query-parameter credentials. Their values are never returned.
transportenum<string>
The upstream transport: HTTP.
One of "HTTP"
auth_typeenum<string>
NONE, HEADERS, OAUTH_AUTO or OAUTH_CLIENT_CREDENTIALS.
One of "NONE", "HEADERS", "OAUTH_AUTO", "OAUTH_CLIENT_CREDENTIALS"
header_namesstring[]
Names of the stored credential headers. Their values are never returned.
oauthobject
A connector's OAuth client registration with its upstream. The client secret is never returned.
Child attributes
- client_idstring
  The OAuth client ID the gateway uses at the upstream.
- registrationstring
  How the client was registered: PRE_REGISTERED (given by you), CIMD (a client ID metadata document) or DCR (dynamic client registration). Absent until the first sign-in or token request.
- has_client_secretboolean
  true when a client secret is stored.
- issuerstring
  The upstream authorization server the registration is bound to.
- scopesstring
  The scopes requested, space-separated.
- authorization_endpointstring
  Where people sign in. Shown for OPENAPI and HTTP connectors only.
- token_endpointstring
  The upstream token endpoint.
global_workspace_accessboolean
Whether every workspace in the organization may use it.
org_connection_for_usersboolean
OAUTH_AUTO: whether a signed-in person without their own connected account may use the organization connection.
statusenum<string>
ACTIVE or DISABLED.
One of "ACTIVE", "DISABLED"
protocol_versionstring
The MCP protocol version the upstream spoke on the last sync.
protocol_eraenum<string>
MODERN or LEGACY, from protocol_version.
One of "MODERN", "LEGACY"
server_namestring
The name the upstream reported on the last sync (a REST connector: the spec's title).
server_versionstring
The version the upstream reported on the last sync.
instructionsstring
Usage instructions the upstream sent for agents, if any.
sync_statusenum<string>
NEVER, OK, FAILED or STALE.
One of "NEVER", "OK", "FAILED", "STALE"
sync_errorstring
Why the last sync failed. Absent unless sync_status is FAILED.
last_synced_atstring<date-time>
When the last successful sync finished (ISO 8601).
last_sync_attempt_atstring<date-time>
When a sync was last attempted (ISO 8601).
created_bystring
The user who created it.
created_atstring<date-time>
When it was created (ISO 8601).
updated_atstring<date-time>
When it was last changed (ISO 8601).
guardrail_slugsstring[]
Guardrails run on every call through this connector, in order. Empty when there are none.

Request

curl -X POST "https://api.vectoraxis.ai/v1/mcp-integrations" \
  -H "Authorization: Bearer $VECTORAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organization": "string",
  "name": "string",
  "url": "string"
}'

VectorAxis is built by GK Labs, a member of NVIDIA Inception.