Skip to main content

MCP servers and OpenAPI import

Two quick ways to give agents many tools at once:

  • MCP server. Register an outside Model Context Protocol server on a project. Its tools become agent tools.
  • OpenAPI import. Read an OpenAPI 3 description and pick operations. Each becomes a tool of a REST API connector.

Either way, each call takes the same path as every connector tool: the policy check, the approval gate, the call_tool audit event, the usage meter and redaction in traces. Calls run in the tool execution service. See Tools and connectors.

Add an MCP server​

  1. Open Connectors, choose New connector, then MCP server.
  2. Enter the server's URL and pick the transport:
    • Streamable HTTP, the default and current MCP transport
    • HTTP + SSE, the older transport
  3. Pick how to authenticate: none, a bearer token, or an API key sent in a header you name. Credentials go to Vault. The server can also act as each user, with that person's own OAuth token. See Act as each user.
  4. Create. Orchestrate asks the server for its tools straight away. Choose Refresh tools later to read a changed list.

Local stdio servers aren't accepted: the cluster doesn't start local processes for tools. Run such a server as a service of its own and register its HTTP address.

Which tools agents get​

Every tool the server lists appears in the connector panel, with the server's own description and its readOnlyHint. Then:

  • Every MCP tool counts as a write at first, so each call waits for a person to approve it. A developer or admin marks the tools that only read as read-only, and those run without approval. The server's readOnlyHint is shown but doesn't decide this.
  • A developer or admin can switch off a tool, which hides it from agents.
  • A tool that is switched off, or that the server no longer lists, counts as a write, and calls to it fail.

An agent keeps the tool definitions it was saved with. Save the agent again to pick up a changed tool.

Network​

Before connecting, the address goes through the connector sandbox: the platform's own services, loopback, link-local and cloud-metadata addresses are refused, and redirects aren't followed. With the SSE transport, the message address the server names must be on the same origin.

If your operator restricts tool execution's outbound traffic, the server's host and port must be on the allowed list. The connector panel shows the host:port to add. On an air-gapped install every MCP server must be listed. See Configuration.

Import an OpenAPI description​

  1. Open Connectors, choose New connector, then REST API.
  2. Open Import from OpenAPI and give the description: upload a file, paste it, or give its URL. JSON and YAML both work.
  3. Pick the operations you want. Each becomes one tool.
  4. Check the authentication the import filled in, add the credentials, and create.

What the import does:

  • Path and query parameters, and the properties of a JSON object body, become the tool's parameters, with their types, enums and descriptions.
  • GET operations read. Every other method writes, so its calls wait for approval.
  • The description's security scheme fills in the authentication: an API key in a header gives API key, HTTP bearer gives Bearer token, OAuth 2 client credentials gives OAuth2 client credentials, and OAuth 2 authorization code gives act as each user.

The import skips header and cookie parameters, request bodies that aren't JSON, Swagger 2.0 documents and remote $refs, and lists each skipped item as a warning. Nothing is stored until you create the connector.

A description fetched from a URL goes through the same sandbox, isn't redirected, and may be at most 5 MB.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →