New VDF AI Enterprise is now available on AWS Marketplace
API Reference

MCP servers

An MCP server is a remote Model Context Protocol server that you register with your deployment. On registration the deployment connects to the server, lists its tools, and adds each one to the tool catalogue under the name mcp__<slug>__<tool>. From then on agents use those tools like any other tool, and each call is forwarded to the server with the credential you stored.

A server is private to you when you register it. You can share it with colleagues through Share a resource, and your administrator can publish it to your whole company. You see your own servers, servers shared with you or with one of your groups, servers published to your company, and servers provided by the deployment. Only the owner can update, refresh or delete a server.

Stored credentials are never returned; responses carry has_credential instead. Put secrets in credential, never in server_url: the URL is returned to everyone who can see the server.

Endpoints 6

Paths are relative to /agent-hub-api

The MCP server object

A registered remote MCP server and the state of its last tool discovery.

Attributes

  • id string

    Unique identifier for the server (a UUID).

  • slug string

    Namespace segment of the server's tool names (mcp__<slug>__<tool>). Unique on the deployment and fixed after registration.

  • display_name string

    Name shown in the product.

  • description nullable string

    Free-text description.

  • server_url string

    URL of the server's MCP endpoint. Visible to everyone who can see the server.

  • transport string

    How the deployment talks to the server: streamable_http (the current MCP HTTP transport) or sse (the older HTTP with server-sent events transport).

    Possible values
    • streamable_http
    • sse
  • auth_type string

    How the stored credential is sent: not at all, as Authorization: Bearer <credential>, or in a custom header.

    Possible values
    • none
    • bearer
    • header
  • has_credential boolean

    Whether a credential is stored for the server. The credential itself is never returned.

  • owner_user_id nullable integer

    Id of the user who registered the server, or null for servers provided by the deployment.

  • company_id nullable integer

    Id of the company the server belongs to.

  • visibility string

    private servers are visible to their owner and to people they are shared with; company servers are visible to everyone in the company.

    Possible values
    • private
    • company
  • is_active boolean

    false once the server has been deleted.

  • status string

    Result of the last discovery. A server in error keeps serving the tools it had before.

    Possible values
    • pending
    • ready
    • error
  • last_error nullable string

    Why the last discovery failed, or null after a successful one.

  • last_synced_at nullable string

    When tools were last discovered successfully (UTC, ISO 8601).

  • consecutive_failures integer

    Number of discovery failures since the last success.

  • tool_count integer

    Number of tools found at the last successful discovery.

  • protocol_version nullable string

    MCP protocol version negotiated with the server, for example 2025-06-18.

  • server_name nullable string

    Name the server reported about itself.

  • server_version nullable string

    Version the server reported about itself.

  • timeout_seconds integer

    Timeout, in seconds, for each request to the server.

  • created_at string

    When the server was registered (UTC, ISO 8601).

  • updated_at string

    When the server was last changed (UTC, ISO 8601).

  • tools array of objects

    The server's active tool catalogue entries. Included when you register, retrieve, update or refresh a server; not included in lists.

    Show child attributes Hide child attributes
    • tool_name string

      Catalogue name of the tool, mcp__<slug>__<tool>. This is the name agents use.

    • remote_tool_name string

      Name of the tool on the MCP server.

    • description nullable string

      Description the server gave for the tool.

    • parameters_schema object

      JSON Schema of the tool's arguments, as the server declared it.

    • tool_type string

      Always mcp_remote for tools of a registered MCP server.

    • mcp_category string

      Always remote for tools of a registered MCP server.

    • mcp_server_id string

      Id of the server that provides the tool.

    • owner_user_id nullable integer

      Owner of the server that provides the tool.

    • is_active boolean

      Whether agents can currently use the tool.

    • default_domain_id nullable string

      Id of the domain the tool is assigned to by default, if any.

    • default_domain_slug nullable string

      Slug of that domain, if any.

    • app_id nullable string

      Always null for tools of a registered MCP server.

    • endpoint_url nullable string

      Always null for tools of a registered MCP server.

    • http_method nullable string

      Always null for tools of a registered MCP server.

    • auth_method nullable string

      Always null for tools of a registered MCP server.

    • created_at string

      When the tool was first imported (UTC, ISO 8601).

    • updated_at string

      When the tool was last updated (UTC, ISO 8601).

The MCP server object 
{
  "id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
  "slug": "ticketing",
  "display_name": "Northwind Ticketing",
  "description": "Create and search tickets in the Northwind service desk.",
  "server_url": "https://mcp.northwind.example.com/mcp",
  "transport": "streamable_http",
  "auth_type": "bearer",
  "has_credential": true,
  "owner_user_id": 42,
  "company_id": 7,
  "visibility": "private",
  "is_active": true,
  "status": "ready",
  "last_error": null,
  "last_synced_at": "2026-09-01T09:30:02.187455",
  "consecutive_failures": 0,
  "tool_count": 2,
  "protocol_version": "2025-06-18",
  "server_name": "northwind-ticketing",
  "server_version": "1.4.0",
  "timeout_seconds": 30,
  "created_at": "2026-09-01T09:30:01.902114",
  "updated_at": "2026-09-01T09:30:02.190873",
  "tools": [
    {
      "tool_name": "mcp__ticketing__create_ticket",
      "description": "Create a support ticket.",
      "mcp_category": "remote",
      "default_domain_id": null,
      "default_domain_slug": null,
      "parameters_schema": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Short summary of the issue."
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "normal",
              "high"
            ]
          }
        },
        "required": [
          "title"
        ]
      },
      "is_active": true,
      "tool_type": "mcp_remote",
      "app_id": null,
      "endpoint_url": null,
      "http_method": null,
      "auth_method": null,
      "owner_user_id": 42,
      "mcp_server_id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
      "remote_tool_name": "create_ticket",
      "created_at": "2026-09-01T09:30:02.011542",
      "updated_at": "2026-09-01T09:30:02.011542"
    }
  ]
}

List MCP servers

GET /agent-hub-api/api/mcp-servers

Returns the active MCP servers visible to the caller.

Returns servers you own, servers shared with you or with one of your groups, servers published to your company, and servers provided by the deployment, sorted by display_name. Deleted servers are not listed. List entries do not include tools; retrieve a server to get them.

Authentication
Bearer token How it works

Parameters

No parameters.

Returns

Returns an object whose servers array holds MCP server objects without tools.

Request 
curl "$VDF_BASE_URL/agent-hub-api/api/mcp-servers" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "servers": [
    {
      "id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
      "slug": "ticketing",
      "display_name": "Northwind Ticketing",
      "description": "Create and search tickets in the Northwind service desk.",
      "server_url": "https://mcp.northwind.example.com/mcp",
      "transport": "streamable_http",
      "auth_type": "bearer",
      "has_credential": true,
      "owner_user_id": 42,
      "company_id": 7,
      "visibility": "private",
      "is_active": true,
      "status": "ready",
      "last_error": null,
      "last_synced_at": "2026-09-01T09:30:02.187455",
      "consecutive_failures": 0,
      "tool_count": 2,
      "protocol_version": "2025-06-18",
      "server_name": "northwind-ticketing",
      "server_version": "1.4.0",
      "timeout_seconds": 30,
      "created_at": "2026-09-01T09:30:01.902114",
      "updated_at": "2026-09-01T09:30:02.190873"
    }
  ]
}

Register an MCP server

POST /agent-hub-api/api/mcp-servers

Connects to an MCP server, imports its tools into the catalogue, and saves the server.

Validates the request, connects to the server, lists its tools, and stores the server as private to you. Each tool is added to the catalogue as mcp__<slug>__<tool>; a tool whose catalogue name is already used by another catalogue entry is skipped. Nothing is saved if the server cannot be reached.

slug is unique on the deployment and cannot be changed later, because agents store the tool names derived from it; it stays taken after the server is deleted. The credential is never returned. Each user can have up to 20 active servers unless your administrator has changed this limit.

Authentication
Bearer token How it works
Permission
Your administrator can limit this to roles that may manage MCP servers.

Body parameters application/json

  • display_name string Required

    Name shown in the product; the first 150 characters are kept. Also accepted as name.

  • server_url string Required

    HTTP or HTTPS URL of the server's MCP endpoint. Also accepted as url. The host must resolve to a public address unless your administrator has allowed it. Do not put secrets in the URL; use credential.

  • slug string

    Namespace for the server's tool names: 2 to 31 characters, lowercase letters, digits, - and _, starting with a letter or digit. When omitted, a slug is derived from display_name.

  • description string

    Free-text description of the server.

  • transport string

    Transport the server speaks: streamable_http for the current MCP HTTP transport, sse for the older HTTP with server-sent events transport.

    Defaults to streamable_http.

    Possible values
    • streamable_http
    • sse
  • auth_type string

    How to send the credential: not at all, as Authorization: Bearer <credential>, or in the header named by header_name.

    Defaults to none.

    Possible values
    • none
    • bearer
    • header
  • credential string

    Secret the server expects. Required when auth_type is bearer or header. Also accepted as token.

  • header_name string

    Header that carries the credential when auth_type is header: letters, digits and hyphens, up to 64 characters.

    Defaults to X-Api-Key.

  • timeout_seconds integer

    Timeout for each request to the server, from 1 to 300 seconds. Defaults to the deployment's setting, which is 30 seconds unless your administrator has changed it.

Returns

Returns server, the new MCP server object with its tools, and tools, the catalogue names that were added, updated and removed.

Errors

  • 400 A required field is missing or invalid, the slug is taken, you have reached the server limit, the server could not be reached, the deployment is not set up to store credentials securely, or registering MCP servers is turned off on this deployment. error says which.
  • 403 Your role does not allow managing MCP servers.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/mcp-servers" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Northwind Ticketing",
    "server_url": "https://mcp.northwind.example.com/mcp",
    "slug": "ticketing",
    "description": "Create and search tickets in the Northwind service desk.",
    "transport": "streamable_http",
    "auth_type": "bearer",
    "credential": "<API_TOKEN>",
    "timeout_seconds": 30
  }'
Response 201 
{
  "success": true,
  "server": {
    "id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
    "slug": "ticketing",
    "display_name": "Northwind Ticketing",
    "description": "Create and search tickets in the Northwind service desk.",
    "server_url": "https://mcp.northwind.example.com/mcp",
    "transport": "streamable_http",
    "auth_type": "bearer",
    "has_credential": true,
    "owner_user_id": 42,
    "company_id": 7,
    "visibility": "private",
    "is_active": true,
    "status": "ready",
    "last_error": null,
    "last_synced_at": "2026-09-01T09:30:02.187455",
    "consecutive_failures": 0,
    "tool_count": 2,
    "protocol_version": "2025-06-18",
    "server_name": "northwind-ticketing",
    "server_version": "1.4.0",
    "timeout_seconds": 30,
    "created_at": "2026-09-01T09:30:01.902114",
    "updated_at": "2026-09-01T09:30:02.190873",
    "tools": [
      {
        "tool_name": "mcp__ticketing__create_ticket",
        "description": "Create a support ticket.",
        "mcp_category": "remote",
        "default_domain_id": null,
        "default_domain_slug": null,
        "parameters_schema": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Short summary of the issue."
            },
            "priority": {
              "type": "string",
              "enum": [
                "low",
                "normal",
                "high"
              ]
            }
          },
          "required": [
            "title"
          ]
        },
        "is_active": true,
        "tool_type": "mcp_remote",
        "app_id": null,
        "endpoint_url": null,
        "http_method": null,
        "auth_method": null,
        "owner_user_id": 42,
        "mcp_server_id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
        "remote_tool_name": "create_ticket",
        "created_at": "2026-09-01T09:30:02.011542",
        "updated_at": "2026-09-01T09:30:02.011542"
      }
    ]
  },
  "tools": {
    "added": [
      "mcp__ticketing__create_ticket",
      "mcp__ticketing__search_tickets"
    ],
    "updated": [],
    "removed": []
  }
}

Retrieve an MCP server

GET /agent-hub-api/api/mcp-servers/{server_id}

Returns one MCP server visible to the caller, with its tools.

Returns the server if you can see it (see List MCP servers). This includes servers that have been deleted, which have is_active: false and no active tools.

Authentication
Bearer token How it works

Path parameters

  • server_id string Required

    Id of the server.

Returns

Returns server, the MCP server object including its active tools.

Errors

  • 404 No MCP server with this id is visible to you.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/mcp-servers/3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "server": {
    "id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
    "slug": "ticketing",
    "display_name": "Northwind Ticketing",
    "description": "Create and search tickets in the Northwind service desk.",
    "server_url": "https://mcp.northwind.example.com/mcp",
    "transport": "streamable_http",
    "auth_type": "bearer",
    "has_credential": true,
    "owner_user_id": 42,
    "company_id": 7,
    "visibility": "private",
    "is_active": true,
    "status": "ready",
    "last_error": null,
    "last_synced_at": "2026-09-01T09:30:02.187455",
    "consecutive_failures": 0,
    "tool_count": 2,
    "protocol_version": "2025-06-18",
    "server_name": "northwind-ticketing",
    "server_version": "1.4.0",
    "timeout_seconds": 30,
    "created_at": "2026-09-01T09:30:01.902114",
    "updated_at": "2026-09-01T09:30:02.190873",
    "tools": [
      {
        "tool_name": "mcp__ticketing__search_tickets",
        "description": "Search tickets by keyword.",
        "mcp_category": "remote",
        "default_domain_id": null,
        "default_domain_slug": null,
        "parameters_schema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string"
            }
          },
          "required": [
            "query"
          ]
        },
        "is_active": true,
        "tool_type": "mcp_remote",
        "app_id": null,
        "endpoint_url": null,
        "http_method": null,
        "auth_method": null,
        "owner_user_id": 42,
        "mcp_server_id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
        "remote_tool_name": "search_tickets",
        "created_at": "2026-09-01T09:30:02.013809",
        "updated_at": "2026-09-01T09:30:02.013809"
      }
    ]
  }
}

Update an MCP server

PUT /agent-hub-api/api/mcp-servers/{server_id}

Updates an MCP server you own, reconnecting to it when the connection settings change.

Send only the fields you want to change. Changing server_url, transport, auth_type or credential reconnects to the server and re-imports its tools; if the reconnection fails, nothing is saved. Setting auth_type to none removes the stored credential, and a new header_name takes effect only when sent together with credential.

slug cannot be changed; register a new server instead.

Authentication
Bearer token How it works
Permission
Your administrator can limit this to roles that may manage MCP servers.

Path parameters

  • server_id string Required

    Id of a server you own.

Body parameters application/json

  • display_name string

    New display name. Cannot be empty.

  • description string

    New description; an empty string clears it.

  • server_url string

    New URL of the server's MCP endpoint, checked as on registration. Also accepted as url.

  • transport string

    New transport.

    Possible values
    • streamable_http
    • sse
  • auth_type string

    New authentication method. bearer and header need credential in the same request.

    Possible values
    • none
    • bearer
    • header
  • credential string

    New secret, replacing the stored one. Also accepted as token.

  • header_name string

    Header that carries the credential when auth_type is header: letters, digits and hyphens, up to 64 characters. Defaults to X-Api-Key.

  • timeout_seconds integer

    New per-request timeout, from 1 to 300 seconds.

  • slug string

    Must equal the current slug if you send it.

Returns

Returns server, the updated MCP server object with its tools, and tools: the catalogue names that were added, updated and removed when the server was reconnected, or null when it was not.

Errors

  • 400 The server does not exist or is not yours, a field is invalid, slug differs from the current one, or reconnecting to the server failed. error says which.
  • 403 Your role does not allow managing MCP servers.
Request 
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/mcp-servers/3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Northwind Service Desk",
    "timeout_seconds": 60
  }'
Response 200 
{
  "success": true,
  "server": {
    "id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
    "slug": "ticketing",
    "display_name": "Northwind Service Desk",
    "description": "Create and search tickets in the Northwind service desk.",
    "server_url": "https://mcp.northwind.example.com/mcp",
    "transport": "streamable_http",
    "auth_type": "bearer",
    "has_credential": true,
    "owner_user_id": 42,
    "company_id": 7,
    "visibility": "private",
    "is_active": true,
    "status": "ready",
    "last_error": null,
    "last_synced_at": "2026-09-01T09:30:02.187455",
    "consecutive_failures": 0,
    "tool_count": 2,
    "protocol_version": "2025-06-18",
    "server_name": "northwind-ticketing",
    "server_version": "1.4.0",
    "timeout_seconds": 60,
    "created_at": "2026-09-01T09:30:01.902114",
    "updated_at": "2026-09-02T11:04:37.664021",
    "tools": [
      {
        "tool_name": "mcp__ticketing__create_ticket",
        "description": "Create a support ticket.",
        "mcp_category": "remote",
        "default_domain_id": null,
        "default_domain_slug": null,
        "parameters_schema": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Short summary of the issue."
            },
            "priority": {
              "type": "string",
              "enum": [
                "low",
                "normal",
                "high"
              ]
            }
          },
          "required": [
            "title"
          ]
        },
        "is_active": true,
        "tool_type": "mcp_remote",
        "app_id": null,
        "endpoint_url": null,
        "http_method": null,
        "auth_method": null,
        "owner_user_id": 42,
        "mcp_server_id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
        "remote_tool_name": "create_ticket",
        "created_at": "2026-09-01T09:30:02.011542",
        "updated_at": "2026-09-01T09:30:02.011542"
      }
    ]
  },
  "tools": null
}

Refresh an MCP server

POST /agent-hub-api/api/mcp-servers/{server_id}/refresh

Lists the tools of an MCP server you own again and updates the catalogue to match.

Reconnects to the server and reconciles its catalogue entries: new tools are added, changed ones are updated, and tools the server no longer lists are deactivated. If the server cannot be reached, its status becomes error, last_error records why, and the tools it already had stay available.

Authentication
Bearer token How it works

Path parameters

  • server_id string Required

    Id of a server you own.

Returns

Returns server, the refreshed MCP server object with its tools, and tools, the catalogue names that were added, updated and removed.

Errors

  • 404 No MCP server with this id is owned by you.
  • 502 The server could not be reached or answered with an error. The server is marked error and keeps its existing tools.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/mcp-servers/3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21/refresh" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "server": {
    "id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
    "slug": "ticketing",
    "display_name": "Northwind Ticketing",
    "description": "Create and search tickets in the Northwind service desk.",
    "server_url": "https://mcp.northwind.example.com/mcp",
    "transport": "streamable_http",
    "auth_type": "bearer",
    "has_credential": true,
    "owner_user_id": 42,
    "company_id": 7,
    "visibility": "private",
    "is_active": true,
    "status": "ready",
    "last_error": null,
    "last_synced_at": "2026-09-03T08:15:20.339184",
    "consecutive_failures": 0,
    "tool_count": 3,
    "protocol_version": "2025-06-18",
    "server_name": "northwind-ticketing",
    "server_version": "1.5.0",
    "timeout_seconds": 30,
    "created_at": "2026-09-01T09:30:01.902114",
    "updated_at": "2026-09-03T08:15:20.342907",
    "tools": [
      {
        "tool_name": "mcp__ticketing__close_ticket",
        "description": "Close a ticket with a resolution note.",
        "mcp_category": "remote",
        "default_domain_id": null,
        "default_domain_slug": null,
        "parameters_schema": {
          "type": "object",
          "properties": {
            "ticket_id": {
              "type": "string"
            },
            "resolution": {
              "type": "string"
            }
          },
          "required": [
            "ticket_id"
          ]
        },
        "is_active": true,
        "tool_type": "mcp_remote",
        "app_id": null,
        "endpoint_url": null,
        "http_method": null,
        "auth_method": null,
        "owner_user_id": 42,
        "mcp_server_id": "3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21",
        "remote_tool_name": "close_ticket",
        "created_at": "2026-09-03T08:15:20.301466",
        "updated_at": "2026-09-03T08:15:20.301466"
      }
    ]
  },
  "tools": {
    "added": [
      "mcp__ticketing__close_ticket"
    ],
    "updated": [
      "mcp__ticketing__create_ticket",
      "mcp__ticketing__search_tickets"
    ],
    "removed": []
  }
}

Delete an MCP server

DEL /agent-hub-api/api/mcp-servers/{server_id}

Deletes an MCP server you own and deactivates its tools.

The server no longer appears in lists and its tools are deactivated, so agents can no longer call them. Its slug stays taken, so a new server cannot reuse it.

Authentication
Bearer token How it works
Permission
Your administrator can limit this to roles that may manage MCP servers.

Path parameters

  • server_id string Required

    Id of a server you own.

Returns

Returns success: true once the server and its tools are deactivated.

Errors

  • 404 No MCP server with this id is owned by you.
  • 403 Your role does not allow managing MCP servers.
Request 
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/mcp-servers/3f1c9a52-8d4e-4b7a-9f2e-6a1d0c5b7e21" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true
}