diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt index ab3e16895..295f4911e 100644 --- a/cspell-allow-list.txt +++ b/cspell-allow-list.txt @@ -531,6 +531,7 @@ storageaccounttype STORAGECLASS Strato strconv +Streamable subchart subcharts subexpression diff --git a/docs/agentic-batch-changes/configuration.mdx b/docs/agentic-batch-changes/configuration.mdx index 49771187f..e4fb84458 100644 --- a/docs/agentic-batch-changes/configuration.mdx +++ b/docs/agentic-batch-changes/configuration.mdx @@ -12,6 +12,8 @@ You can add guidance on the **Agents** page of your Batch Changes settings, at ` settings](/deep-search#customization). +To give the agent access to systems outside your code, such as issue trackers, internal documentation, or CI, add [connectors](/agentic-batch-changes/connectors). + ### Guidance and skills Guidance and skills configured here apply only to the coordinating agent you talk to directly, which researches your codebase, writes the plan, and manages the rollout. @@ -65,6 +67,7 @@ Within a coding agent step, the agent has: - **Full MCP access under your identity.** The Sourcegraph MCP tools are available and authenticated as you, so the agent operates with your permissions. - **Access to the code being worked on.** The workspace's repository checkout is available to the agent as it makes changes. +- **Your connectors.** If you have user or shared [connectors](/agentic-batch-changes/connectors) configured, the agent can call their tools with your connections. We currently support [Claude Code](https://claude.com/product/claude-code) and [Codex](https://openai.com/codex) as native coding agent steps. diff --git a/docs/agentic-batch-changes/connectors.mdx b/docs/agentic-batch-changes/connectors.mdx new file mode 100644 index 000000000..7a404d8b7 --- /dev/null +++ b/docs/agentic-batch-changes/connectors.mdx @@ -0,0 +1,70 @@ +# Connectors + +Connectors give Agentic Batch Changes access to tools outside your code, such as issue trackers, internal documentation, observability tools, and CI systems, giving the agent all context required. Connectors let you bring any compatible [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server. + +Connectors are available to the coordination agent, as well as coding agents used in [coding agent steps](/agentic-batch-changes/configuration#coding-agent-steps). + +Connector calls appear as part of the agent transcript, so you can follow along what the agent is doing. When a task needs a connector you haven't connected, a **Connect** button for that connector appears right above the message input, visible only to the author of the thread. + +## Setup + +Administrators manage connectors under **Administration → Integrations → Connectors**. This requires the `Integration management` write permission. + +Connectors use MCP's Streamable HTTP transport, and fall back to the older HTTP with Server-Sent Events transport. MCP servers that only run locally over standard input and output (stdio) are not supported. + +### Authentication + +| Option | When to use it | +| ----------------------- | --------------------------------------------------------------------------------------------- | +| **OAuth** (recommended) | The server supports OAuth sign-in. Each user signs in with their own account. | +| **No authentication** | The server is public, or it's on your network and needs no credentials. | +| **Bearer token** | The server accepts one shared token, such as a service account's API key. All users share it. | +| **Per-user API token** | Each user should use their own personal access token, such as a Linear or Sentry API key. | + +When you choose OAuth, Sourcegraph discovers the server's authorization server automatically, following the [MCP authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization). If the authorization server supports dynamic client registration, Sourcegraph registers itself as an OAuth client, and you don't need to enter anything else. Otherwise, register an OAuth client with the authorization server using the redirect URL `https://${YOUR_INSTANCE_URL}/.auth/connectors/callback`, and enter the client ID and, if the server requires it, the client secret. + +### Managing tools + + + For connectors with per-user authentication, Sourcegraph lists the tools + once the first user connects. + + +Each connector lists the tools its server provides, with their descriptions and what they may do, based on hints from the server: + +- **Read-only**: the tool doesn't modify data. +- **Writes**: the tool may modify data, but doesn't delete or overwrite it. +- **Destructive**: the tool may delete or overwrite data. +- **Unknown effects**: the server gives no hints, so the tool may delete or overwrite data. + +Tools are enabled by default, except destructive tools and tools with unknown effects. + +Sourcegraph refreshes each connector's tools every six hours, and when an administrator selects **Refresh tools**. New destructive tools start disabled. + +If the server rejects a connector's bearer token or custom header credentials, during a refresh or when an agent calls a tool, Sourcegraph notifies the site administrators. For personal connectors, it notifies the owner instead. The connector list also shows a warning on the connector. + +### Network access + +Connectors that administrators add can reach the same networks as [code host connections](/admin/code-hosts): + +- On self-hosted instances, they can reach servers on your internal network, unless [`EXTERNAL_DENY_LIST`](/self-hosted/network-filtering) blocks them. Requests come from the `frontend` and `worker` services. +- On Sourcegraph Cloud, they reach servers in your private network through private connectivity, such as [Sourcegraph Connect](/cloud/private-connectivity-sourcegraph-connect), [GCP Private Service Connect](/cloud/private-connectivity-gcp), or [AWS PrivateLink](/cloud/private-connectivity-aws). Ask your account team to add the MCP server's hostname. + +Personal connectors can only reach public addresses by default. To let them reach other addresses on a self-hosted instance, use [`UNTRUSTED_EXTERNAL_ALLOW_LIST`](/self-hosted/network-filtering). + +## Using connectors as a user + +Your connectors are in your user settings under **Connectors**. The page lists the connectors your administrator added and your personal connectors, with the tools each one provides. For any connectors that require user-specific authentication, you need to connect to them from here: + +- **Connect** signs you in to an OAuth connector. **Disconnect** removes your connection. +- For connectors with per-user API tokens, enter your token and select **Save token**. **Remove token** deletes it. + +The **Use in Agentic Batch Changes** checkbox turns a connector on or off for your agentic batch changes. + +When a connection expires or is revoked, Sourcegraph notifies you in Sourcegraph and by email, and the connector shows **Connection expired** with a **Reconnect** button. Agents can't use the connector until you reconnect. + +### Personal connectors + +On the **Connectors** settings page, users can also add their own connectors that only their agents use. This requires the `CONNECTORS#WRITE_USER` [permission](/admin/access-control). + +Personal connectors can only reach MCP servers on public addresses. You manage their tools the same way administrators manage shared ones. diff --git a/docs/self-hosted/encryption.mdx b/docs/self-hosted/encryption.mdx index 34aef4e6c..61bc51e1e 100644 --- a/docs/self-hosted/encryption.mdx +++ b/docs/self-hosted/encryption.mdx @@ -39,6 +39,10 @@ We distinguish encrypted and unencrypted records in the database, so partially e // encrypts data in webhook_logs "webhookLogKey": { // ... + }, + // encrypts data in connectors and connector_user_tokens + "connectorKey": { + // ... } } } diff --git a/docs/self-hosted/network-filtering.mdx b/docs/self-hosted/network-filtering.mdx index cd54166a1..d50bee0d3 100644 --- a/docs/self-hosted/network-filtering.mdx +++ b/docs/self-hosted/network-filtering.mdx @@ -22,7 +22,7 @@ This would deny all connections to hosts in the private network and github.com. ## Untrusted External Connections -Codemonitors, webhooks and Cody URL context are limited to only be able to access public IP addresses by default. This behavior can be changed with the `UNTRUSTED_EXTERNAL_ALLOW_LIST` environment variable, which configures the allowlist. +Codemonitors, webhooks, Cody URL context and [personal connectors](/agentic-batch-changes/connectors#personal-connectors) are limited to only be able to access public IP addresses by default. This behavior can be changed with the `UNTRUSTED_EXTERNAL_ALLOW_LIST` environment variable, which configures the allowlist. ### Example Configuration diff --git a/src/data/navigation.ts b/src/data/navigation.ts index e224d2b72..a4c5efff0 100644 --- a/src/data/navigation.ts +++ b/src/data/navigation.ts @@ -38,6 +38,10 @@ export const navigation: NavigationItem[] = [ { title: 'Configuration and administration', href: '/agentic-batch-changes/configuration' + }, + { + title: 'Connectors', + href: '/agentic-batch-changes/connectors' } ] },