---
title: "Update Agent Connections"
method: PUT
path: "/agents/connections"
tags: ["Agents"]
---

# Update Agent Connections

`PUT /agents/connections`

Bulk save the tenant's agent connections. Secrets are encrypted at rest.

Service-layer ``ValueError`` (external MCP URL validation, intra-document
duplicate id guard) surfaces as 422 with the message so the FE can point
at the offending row. Unhandled, these would land as 500.

## Request body

- AgentConnections — Tenant-scoped saved agent connections. Stored in MongoDB agent_connections collection. The bulk shape behind ``GET /agents/connections`` and ``PUT /agents/connections``: per-tenant lists of LLM, MCP, and HTTP connection profiles that agents reference at deploy time. The Mongo collection is ``agent_connections``; per-row CRUD lives at ``/agents/connections/{kind}`` (see ``app.services.agent_connections_service``).
  - `llmConnections` AgentLlmConnection[] — Saved LLM connections - credentials + default tuning. Reusable across many agents.
    - `id` string, nullable — Server-generated UUID — stable across renames. Null on first create, BE assigns.
    - `name` string, required — User-facing name; unique per tenant by FE convention
    - `provider` 'anthropic' | 'openai' | 'openai-responses' | 'ollama' | 'azure' | 'azure-openai' | 'bedrock' | 'qwen' | 'openai-compatible', required — Unified LLM provider enum. A single ``AgentLlmConnection`` row carries one provider and a set of capabilities (chat / embedding). ``PROVIDER_CAPABILITIES`` below pins which capabilities each provider can serve — picked by the FE Connections drawer and re-validated server-side on every write.
    - `apiKey` string — API key — KMS-wrapped at rest, masked on GET
    - `baseUrl` string, nullable — Base URL for Ollama / Azure / self-deployed OpenAI- or Anthropic-compatible servers (vLLM, LocalAI, TGI, LM Studio, LiteLLM gateways)
    - `capabilities` ConnectionCapability[], required — Non-empty list of capabilities this connection powers. Each entry must be allowed by the provider per ``PROVIDER_CAPABILITIES``, and each listed capability must have its defaults block populated.
    - `chat` ChatDefaults — Default tuning for the ``chat`` capability of a saved LLM connection. Carries the same shape as ``AgentLlmConfig`` (the inline per-agent blob): model + sampling controls + reasoning controls. The wizard prefills these into ``agentConfig.llm`` and the user can override per-agent. ``None`` on any optional field means "use the matrix default at the picked model" so reasoning-only OpenAI models with no temperature don't 422 on save.
      - `model` string — Default chat model, e.g. claude-sonnet-4-20250514. Empty = fill at agent creation.
      - `temperature` number, nullable — Default sampling temperature (null = matrix-skipped)
      - `maxTokens` integer, nullable — Default max output tokens (null = matrix-skipped)
      - `timeout` integer, nullable — Default request timeout (seconds, null = matrix-skipped)
      - `reasoningEffort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable — Default reasoning effort. Accepted set is per-model — the matrix in ``app/utils/llm_capabilities.py`` rejects values not in ``caps.reasoning_effort_values`` for the picked (provider, model).
      - `thinkingBudgetTokens` integer, nullable — Default Anthropic Claude 4 extended-thinking budget (tokens). Non-null enables thinking.
      - `ollamaThink` boolean, nullable — Default Ollama 'think' toggle for reasoning models
      - `maxRetries` integer, nullable — Universal — max retry attempts on LLM call. Accepted by every provider.
      - `region` string, nullable — Bedrock chat: AWS region (e.g. us-east-1). Ignored for non-bedrock providers.
      - `strict` boolean, nullable — openai-responses: enable JSON-schema strict mode. Ignored for other providers.
      - `store` boolean, nullable — openai-responses: server-side response storage flag. Ignored for other providers.
      - `instructions` string, nullable — openai-responses: system-level instructions passed as a top-level Responses param.
      - `additionalKwargs` object, nullable — openai-responses / azure-openai: free-form extra request params forwarded verbatim by the runtime. Use for provider-specific fields not modelled above.
      - `apiVersion` string, nullable — azure-openai: Azure OpenAI API version (e.g. '2024-02-01'). Required for azure-openai.
      - `azureEndpoint` string, nullable — azure-openai: Azure resource endpoint (e.g. https://<resource>.openai.azure.com). Required.
      - `azureUrlPathMode` 'AUTO' | 'LEGACY' | 'UNIFIED', nullable — azure-openai: URL path resolution — AUTO / LEGACY / UNIFIED. Optional.
    - `embedding` EmbeddingDefaults — Default tuning for the ``embedding`` capability of a saved LLM connection. Embedding-only fields — no temperature / reasoning controls because embedding endpoints don't accept them. The KB wizard prefills these into ``KBEmbeddingConfig`` and the user can override per-KB.
      - `model` string — Default embedding model, e.g. text-embedding-3-small. Empty = fill at KB creation.
      - `dimensions` integer, nullable — Output embedding dimensions override (provider-dependent)
      - `batchSize` integer — Records per embedding batch call
      - `region` string, nullable — AWS region for bedrock embedding provider (e.g. us-east-1). Ignored for non-bedrock rows.
      - `maxRetries` integer, nullable — Bedrock retry cap. Ignored for non-bedrock rows.
    - `description` string, nullable — Optional human-readable context for the connection
  - `mcpConnections` union[] — Saved MCP connections (external-source only)
    - union
      - StreamkapMcpConnection — A saved Streamkap MCP server connection. Authenticated via a pasted Project Key credential file in ``headers["X-Streamkap-Project-Key"]``. The BE structurally validates the blob on save, encrypts every header value at rest, and the MCP server (``streamkap-tools``) enforces the PK's stored ``tool_profile`` / ``allowed_tools`` / ``blocked_tools`` scoping per session.
        - `source` 'streamkap' — Discriminator - must be 'streamkap' for this variant
        - `name` string, required — Connection name (e.g. 'Production Streamkap MCP')
        - `serverUrl` string
        - `headers` object — Auth headers. Set 'X-Streamkap-Project-Key' to the base64-encoded credential file downloaded when the Project Key was created.
      - ExternalMcpNoneConnection — External MCP with no authentication header (public / open servers).
        - `source` 'external' — Discriminator - must be 'external'
        - `name` string, required — Connection name (e.g. 'AWS Knowledge', 'Zapier Personal')
        - `serverUrl` string, required
        - `authMode` 'none', required
      - ExternalMcpBearerConnection — External MCP authenticated via ``Authorization: Bearer <token>``.
        - `source` 'external' — Discriminator - must be 'external'
        - `name` string, required — Connection name (e.g. 'AWS Knowledge', 'Zapier Personal')
        - `serverUrl` string, required
        - `authMode` 'bearer', required
        - `bearerToken` string, required — Bearer token - encrypted at rest, masked on GET
      - ExternalMcpHeaderConnection — External MCP authenticated via a single custom header (API-key style).
        - `source` 'external' — Discriminator - must be 'external'
        - `name` string, required — Connection name (e.g. 'AWS Knowledge', 'Zapier Personal')
        - `serverUrl` string, required
        - `authMode` 'header', required
        - `headerName` string, required — HTTP header name (RFC 7230 token alphabet, narrowed)
        - `headerValue` string, required — Header value - encrypted at rest, masked on GET
  - `httpConnections` AgentHttpConnection[] — Saved HTTP API connections. Referenced by HTTP tool rows via ``connectionId`` to inherit baseUrl + headers without duplicating them per tool.
    - `id` string, nullable — Server-generated UUID - stable across renames. Null on first create, BE assigns.
    - `name` string, required — User-facing name; unique per tenant by FE convention (e.g. 'Stripe API')
    - `baseUrl` string, nullable — Base URL prepended to a referencing tool's relative URL. Tools with an absolute URL ignore this. Optional - a connection can be header-only (e.g. shared auth across hosts).
    - `headers` object — HTTP headers merged into every referencing tool's request. Values are KMS-encrypted at rest and full-masked on GET.
    - `description` string, nullable — Optional human-readable context for the connection
  - `vectorStoreConnections` AgentVectorStoreConnection[] — Lightweight vector store credentials (apiKey + endpoint). Used by KBs and agent long-term memory.
    - `id` string, nullable — Server-generated UUID. Null on first create, BE assigns.
    - `name` string, required — User-facing name
    - `provider` 'pgvector' | 'pinecone' | 'milvus' | 'opensearch' | 'elasticsearch' | 's3vectors' | 'redis', required — Vector-store providers supported by the Flink runtime (integration guide §3b.4). Two shape families: - **Typed-field providers** — ``pgvector`` and ``pinecone``. Each has a fixed set of named fields on ``AgentVectorStoreConnection``. - **Pass-through providers** — ``milvus``, ``opensearch``, ``elasticsearch``, ``s3vectors``. Each carries a free-form ``properties`` map that gets copied straight into the framework's ``ResourceDescriptor.addInitialArgument(key, value)`` pairs at deploy time. Framework validates required keys at open-time. ``redis`` is retained for legacy saved connections but is not accepted by the current runtime.
    - `apiKey` string — Pinecone API key — KMS-wrapped at rest, masked on GET
    - `endpoint` string, nullable — Pinecone index host URL
    - `defaultNamespace` string, nullable — Default namespace / collection (overridable per KB or agent)
    - `allowHashFallback` boolean — Opt in to the non-semantic hash-embedding fallback when the vector index lacks integrated inference. Default False = fail-hard (throws instead of silently degrading recall).
    - `jdbcUrl` string, nullable — pgvector: `jdbc:postgresql://host:port/db`. Never embed userinfo here; put credentials in `username` / `password`.
    - `username` string, nullable — pgvector username. Supports `${SECRET:...}` template.
    - `password` string, nullable — pgvector password. Supports `${SECRET:...}` template.
    - `table` string, nullable — pgvector table name used as the vector collection.
    - `dims` integer, nullable — pgvector: embedding output dimensions. `0`/unset inherits from the embedding model. Must match the embedding model's output.
    - `metric` string, nullable — pgvector distance metric. Only `cosine` is currently supported.
    - `properties` object, nullable — Free-form `Map<String, Object>` for pass-through providers. Copied straight into the framework's `ResourceDescriptor.addInitialArgument` pairs at deploy time. Framework validates required keys at open-time. Not used for `pinecone` or `pgvector` (they have named typed fields).
    - `description` string, nullable — Optional human-readable context

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/streamkap/apis/streamkap-rest-api.md) · [All operations](https://skmtc.net/streamkap/apis/streamkap-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/streamkap/streamkap-rest-api/revisions/e9ce8221bac6/schema)