Register and configure a tool server

Use this guide to register an MCP tool server with Vectara by selecting the right transport protocol, and wire credentials so your agents can call the tools it exposes.

Before you begin

You need:

• A running MCP server with a reachable URI.
• An API key or personal API token with the agent_administrator role to create, update, delete, or sync a tool server. The agent_developer role is sufficient to list or get.

Step 1: Choose an MCP specification

Every tool server uses one of two MCP specifications. Set transport in the request body to the value that matches your server's MCP version:

Value	MCP specification	When to use
sse	November 2024	Most existing MCP servers.
streamable-http	March 2025	Servers built to the 2025-03-26 spec.

transport is a required field. Use sse unless your MCP server documentation explicitly targets the March 2025 spec.

Step 2: Register the tool server

Send POST /v2/tool_servers. The name, type, uri, and transport fields are required. type must be "mcp".

REGISTER AN MCP TOOL SERVER

Code example with multiple language options.bashjson

1

Vectara immediately synchronizes with the server to discover its tools. The tools become available for use by any agent in your account.

Step 3: Configure authentication

The auth field tells Vectara how to authenticate when it connects to the MCP server. Three types are supported.

Bearer token

Use bearer when the server accepts a static Authorization: Bearer <token> header.

BEARER TOKEN AUTH

Code example with json syntax.json

1

Custom header

Use header when the server expects a credential in a named header other than Authorization, such as x-api-key.

CUSTOM HEADER AUTH

Code example with json syntax.json

1

OAuth 2.0 client credentials

Use oauth_client_credentials when the server requires an OAuth 2.0 access token obtained via the client credentials grant. Vectara fetches and refreshes the token automatically.

OAUTH 2.0 CLIENT CREDENTIALS AUTH

Code example with json syntax.json

1

caution

token_endpoint is typed as a plain string in the schema (format: uri). It is not a field where {"$ref": "..."} substitution fires. If you need different OAuth tenants per agent, register a separate tool server per tenant.

Step 4: Wire credentials to an agent

The auth field covers the connection from Vectara to the MCP server. The tools that the server exposes may themselves need credentials to call downstream services (for example, a Jira tool that needs a Jira API token). There are two patterns for supplying those.

Service-account credentials (shared across sessions)

Use this pattern when a single shared credential is appropriate for all agent sessions — for example, a read-only service account for an internal wiki.

An admin stores the credential on the agent once using PATCH /v2/agents/{agent_key}/secrets. Every session then uses the credential via a $ref in the tool's argument_override, without the caller ever seeing the plaintext.

STORE A SHARED CREDENTIAL AND REFERENCE IT FROM A TOOL

Code example with multiple language options.bashjson

1

The credential is encrypted at rest, never returned in plaintext by any read operation, and masked in session event logs. See Agent secrets for the full reference on storing, rotating, and removing secrets.

Per-user credentials (session-scoped)

Use this pattern when each session caller authenticates with their own credential — for example, each user's personal Salesforce token.

The caller passes the credential in session.metadata when starting a session. The tool configuration on the agent references it with {"$ref": "session.metadata.<key>"}. The credential exists only for the lifetime of that session.

PASS A PER-USER CREDENTIAL AT SESSION START

Code example with multiple language options.bashjson

1

	Service-account (agent.secrets)	Per-user (session.metadata)
Who supplies it	Admin, once	Caller, each session
Scope	All sessions on the agent	One session only
Encrypted at rest	Yes	No — metadata is plaintext
Masked in session events	Yes	No
Use when	Shared service accounts, read-only integrations	User-delegated access, OAuth tokens tied to a specific person

For OAuth refresh token flows and a full reference of credential patterns across all tool types, see Connector authentication.

Manage tool servers

After registration, use these operations to keep tool servers current.

Synchronize

When the MCP server adds, removes, or changes tools, trigger a sync to update Vectara's copy of the tool list.

curl -X POST https://api.vectara.io/v2/tool_servers/$TOOL_SERVER_ID/sync \
  -H "x-api-key: $VECTARA_API_KEY"

A 204 response means synchronization succeeded.

Update

Use PATCH /v2/tool_servers/{tool_server_id} to change any field (URI, auth, transport, enabled status). Only fields present in the request body are updated.

curl -X PATCH https://api.vectara.io/v2/tool_servers/$TOOL_SERVER_ID \
  -H "x-api-key: $VECTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Delete

curl -X DELETE https://api.vectara.io/v2/tool_servers/$TOOL_SERVER_ID \
  -H "x-api-key: $VECTARA_API_KEY"

Deletion is permanent and removes all associated tool registrations. Agents that referenced those tools will fail on the next invocation that tries to use them.

Required roles summary

Operation	Minimum role
List, get	agent_developer
Create, update, delete, sync	agent_administrator

Related

• Agent secrets — store, rotate, and reference encrypted credentials
• Sessions — pass per-user credentials in session metadata
• Model Context Protocol (MCP) — how MCP connects agents to external tools
• Custom tools — build tools without an MCP server