# MCP Clients

## Overview

An **MCP Client** is a saved configuration for connecting _out_ to an external
[Model Context Protocol](https://modelcontextprotocol.io) server so your agents
can call the tools it exposes. You manage clients from **MCP Clients** in the
left navigation, then reference a client from an agent's
[MCP Client Call step](https://seclai.com/docs/agent-steps/integration#mcp-client-call-step).

Each client stores a name, the server's streamable‑HTTP URL, and how to
authenticate. Connection details and secrets live on the client — agent steps
only reference the client by id, so the same server can be reused across many
agents and updated in one place.

When adding a client, the first step — **Choose a server** — lets you search a
directory of well‑known MCP servers (grouped by category) and pick one; the next
step opens a form tailored to your choice. Servers marked **Managed** connect
with Seclai's own OAuth app (no setup — you just pick permissions); the rest
pre‑fill the verified URL and you supply your own auth. A few entries are marked
**Setup guide** — these vendors (e.g. Google Cloud) don't offer a single hosted
endpoint but document how to stand one up; the card links to their setup docs
instead. To connect a server that isn't in the catalog, choose **Add a custom
server** and enter its URL and authentication yourself.

## Preconfigured Servers

Seclai keeps a catalog of well‑known MCP servers so you don't have to track down
endpoints and auth settings yourself. Browse them on the
**[MCP Server Catalog](https://seclai.com/mcp-servers)** — search by name or tool, preview the tools
each server exposes, and add one to your account in a click. **Managed** servers
connect with Seclai's own OAuth app (one click, no setup); **OAuth**/**API key**
servers you authenticate with your own credentials; **Setup guide** entries link
to a vendor's instructions for standing up their endpoint. The same catalog
appears in the **Choose a server** step when you create a client.

## Slack: User vs Bot

The catalog offers two managed Slack integrations. Pick based on attribution and
whether you need search:

- **Slack (User)** acts as the person who authorizes the connection. Messages
  post **as that user** (with a “Sent using Seclai” footer) and reads use their
  access. It's the only option that can **search** Slack — Slack's search API
  requires a user token. Choose it when you need search or want activity
  attributed to a specific person.
- **Slack (Bot)** acts as the **app/bot** — clean attribution, no impersonation
  and no footer. It can post messages and read channels, history, users, and
  reactions, but it **cannot search** (bots have no search API). Choose it when
  you don't want agent activity to look like it came from a real person.

Both connect the same way (managed OAuth, one click) and live side by side on the
**MCP Clients** page — you can add either or both.

## Creating a Client

1. Open **MCP Clients** and choose **Add MCP Client**.
2. Give it a **name** and the server's **URL**. The URL must be `https://` and
   publicly reachable.
3. Choose an **authentication** method (below) and save.

## Authentication

- **None** — the server requires no credentials.
- **API key / bearer** — Seclai sends an API key on every request. By default it
  is sent as an `Authorization: Bearer <key>` header; set a custom **header
  name** to send the raw key under a different header. The key is stored
  securely and is never shown again once saved — leave the field blank when
  editing to keep the existing key, or enter a new value to replace it.
- **OAuth** — Seclai performs an OAuth authorization‑code flow with the server.
  Most hosted servers register automatically — just enter the server URL and
  click **Connect with OAuth** on the client's detail page to complete the
  interactive authorization in your browser. Once connected, Seclai stores and
  automatically refreshes the access token, so agent runs (which have no human
  present) can keep calling the server. Some servers do **not** support
  automatic (dynamic) client registration — GitHub's remote MCP server
  (<code>https://api.githubcopilot.com/mcp/</code>) is one example. For those you
  have three options, easiest first:
  - **Managed provider** — if a **Provider** dropdown offers the server (e.g.
    “GitHub (managed)”), pick it. Seclai connects with its own OAuth app, so
    there's nothing to register — just name the client, choose which
    **permissions** to request (a recommended set is pre‑selected), save, and
    **Connect with OAuth**. You confirm the same permissions on the provider's
    consent screen. Seclai's app credentials stay server‑side and are never
    shown. Changing the selected permissions later requires reconnecting.
  - **API key / bearer** — use bearer auth with a personal access token (GitHub
    accepts a PAT sent as an <code>Authorization: Bearer …</code> header).
  - **Your own OAuth app** — create an OAuth app on the server and enter its
    client ID (and secret, if any) under **Advanced OAuth settings**, then
    reconnect.

## Changing the connected account

To connect a **different account** on the provider (e.g. a different Dropbox or
GitHub login), it isn't enough to just **Disconnect** and reconnect in Seclai:
the provider remembers that you already authorized Seclai for the account you're
signed into, and will silently re-issue access to **that same account** — which
is why reconnecting can complete without ever showing the provider's sign‑in
screen. To switch accounts:

1. On the client's **Configuration** tab, click **Disconnect** (this revokes and
   deletes Seclai's stored tokens for this client).
2. In your browser, **sign out** of the provider — or, better, remove Seclai from
   the provider's connected/authorized apps (e.g. **Dropbox → Settings →
   Connected apps**, **GitHub → Settings → Applications**). This clears the
   remembered grant so the next authorization starts fresh.
3. Sign into the account you want, then click **Reconnect with OAuth**. For a
   **managed provider**, Seclai always requests the provider's approval screen on
   reconnect, so you can review and authorize with the intended account. For a
   **custom OAuth server** the approval screen only appears if that server
   prompts for it — step 2 above is what guarantees a fresh sign‑in either way.

## Browsing the Server's Tools

A client's detail page shows the **Tools** the server exposes. Click
**Refresh** to connect with the configured authentication and fetch the latest
catalog; Seclai stores it (with a "last updated" timestamp) so you can browse
each tool's description and parameters — name, type, whether it's required, and
allowed values — without reconnecting every time. Refreshing also confirms your
credentials work. If a refresh fails, the previously fetched catalog is kept so
the list never blanks out.

## Using in Agents

There are two ways to call MCP tools from an agent:

**Fixed call — the MCP Client Call step.** Add an **MCP Client Call** step,
select the client, and pick a tool (use **Refresh tools** to fetch the live
list). Provide the tool's arguments as key/value pairs — each value supports
[string substitutions](https://seclai.com/docs/agent-steps) such as `{{input}}` or
`{{step.<id>.output}}`. The tool's result becomes the step's output. See the
[MCP Client Call step reference](https://seclai.com/docs/agent-steps/integration#mcp-client-call-step)
for field details. Use this when you know exactly which tool to call.

**Model-chosen calls — inside a Prompt Call step.** A **Prompt Call** step has
an **MCP server tools** selector (under Advanced options). Pick a client and
enable the tools you want the model to be able to call; during the step the
model decides if and when to invoke them and feeds the results back into its own
reasoning. Use **Add all** when a client exposes a handful of tools, or select
individually for larger servers. Up to **20** MCP tools can be enabled on a
single prompt step (to keep the model's context manageable). Refresh a client's
tools first so its catalog is available to choose from.

## Pointing a Client at Seclai Itself

You can point an MCP client at Seclai's own MCP server so an agent can call
Seclai management tools (for example to read alerts, run another agent, or triage
governance evaluations). When a tool runs **from inside an agent**, a restricted
set applies — a deliberate safeguard so that untrusted content flowing through a
run can't drive the agent into destructive or data-exfiltrating actions:

- **Blocked from agents:** deleting resources; changing governance settings,
  policies, or a policy's knowledge bases; rewriting an agent's definition;
  creating or repointing MCP clients; transferring resources between accounts or
  switching organizations; dismissing all model alerts or cancelling a pending
  human-in-the-loop request; and **bulk data exports** (export is a human
  data-portability feature, not an agent action).
- **Allowed:** reading/listing, running agents, knowledge-base and source
  configuration, governance evaluation triage, and other ordinary operations.

If an agent tries a blocked tool it receives a clear "not available to
agent-originated calls" error — that is expected, not a bug. Agents are also
**depth-capped** so an agent calling another agent (or itself) can't recurse
without bound, and a `webhook_call` step cannot be pointed back at Seclai's own
API to work around these limits. If you need a blocked capability in automation,
do it from your editor/CLI (where the full toolset is available) or ask us about
a purpose-built tool.

## Monitoring: Agents, Calls & Alerts

A client's detail page has tabs for keeping an eye on how it's used:

- **Agents** — every agent whose workflow references this client, either through
  an MCP Client Call step or MCP tools enabled on a Prompt Call step. This is the
  same list that protects the client from accidental deletion (below).
- **Calls** — a history of the tool calls your agents have made to this server
  during agent runs, newest first. Each row shows the tool name, whether it
  succeeded or failed, how long it took, and which agent made the call; filter by
  status or time range and page through the results. (Interactive **Refresh** and
  test‑connection calls are not recorded here — only calls made during real agent
  runs.)
- **Alerts** — opt in to be notified when calls to this client misbehave. Five
  alert types are available: a **failed call**, **consecutive failures**, an
  **error‑rate spike**, a **call burst** (too many calls in a window), and an
  **unusually slow call** (relative to this client's own history). Configure them
  per‑client here, or set account‑wide defaults (applied to every client) from
  the account **Alerts** page. Triggered alerts appear in your alerts list and are
  emailed to the configured recipients.

## Security

Seclai only connects to public `https://` endpoints — private, loopback, and
link‑local addresses are rejected (for the server URL, the OAuth server URL,
and every endpoint discovered during the OAuth flow), and redirects to such
addresses are not followed. Stored API keys and OAuth client secrets are never
returned by the API or shown in the UI after they're saved. Error messages
recorded for failed tool calls are scrubbed of credentials and truncated before
being stored or emailed. A client that is still referenced by an agent cannot be
deleted — Seclai blocks the deletion and lists the agents using it (see the
**Agents** tab) so you can detach it first. Deleting a client
removes Seclai's stored copy of its OAuth access/refresh tokens and makes its
saved configuration inaccessible; the underlying secrets are fully purged when
you close your account. (Deletion removes Seclai's tokens but does not revoke
them at the provider — revoke there too if the grant must be invalidated
immediately.)

For a connected OAuth client you can also **Disconnect** (from its
**Configuration** tab) without deleting it: this revokes Seclai's stored OAuth
tokens but keeps the client, its alert configs, call history, and agent wiring
intact, so you can reconnect later without re-creating it. Disconnecting is also
available programmatically via the `disconnect_mcp_client` MCP tool.

## MCP Tools

MCP clients can also be managed programmatically through Seclai's own MCP
server: `list_mcp_clients`, `get_mcp_client`, `create_mcp_client`,
`update_mcp_client`, `delete_mcp_client`, `disconnect_mcp_client` (revoke a
connected OAuth client's tokens without deleting it), `test_mcp_client_connection`,
`refresh_mcp_client_tools` (fetch and cache the server's tool catalog),
`describe_mcp_client_tools` (the cached tools in compact form, with the
`mcp:<client_id>:<tool_name>` IDs to enable on a prompt-call step), and
`get_agents_using_mcp_client` (the agents referencing a client — check this
before deleting one), and `list_mcp_client_calls` (the tool-call history shown
on the Calls tab, with status/time filters). Alerts on a client are managed with the standard
`list_alert_configs` / `create_alert_config` tools: pass `mcp_client_id` for a
specific client, or use `scope='mcp_client'` (list) / omit the id (create) for
account‑wide defaults. The preconfigured server catalog is also exposed
read-only through `list_mcp_catalog` (browse the directory of popular servers)
and `list_managed_providers` (the managed-OAuth providers configured on this
deployment). Secrets are never returned by these tools, and the
interactive OAuth authorization must still be completed in the web app.

## Next Steps

- [MCP Client Call step](https://seclai.com/docs/agent-steps/integration#mcp-client-call-step)
- [Agent Steps Overview](https://seclai.com/docs/agent-steps)