Connections (MCP)

A connection is an outside service the agentic runtime is allowed to act on: read a Slack channel, search a Notion workspace, draft a Gmail message, post to Discord.

You do not write code to add one. You name where the service lives. The runtime then goes and knocks on the door — it opens a session, asks the service what tools do you have?, and writes the answer into its own tool registry. From that moment those tools exist for your agents by name.

The protocol it knocks with is MCP (the Model Context Protocol) — a small, standard way for a program to publish a list of callable tools. Anything that speaks MCP can be connected, not only the four services that ship in the box.

Before you start

The connection commands talk to a running runtime, so start one:

kx serve --dev-allow-local

Leave that running in its own terminal. Everything below runs in a second one.

The four bundled connectors

Four connectors are maintained alongside kortecx as small standalone programs. Each is a separate process — it is never linked into the runtime — and each reads its credential from a name, never from a value you type into a command that uses it.

A connector is its own binary, so it has to be present on this machine before you connect anything — beside your kx executable, or on your PATH. kx connections doctor is a local check: it does not need the runtime and does not touch the network.

kx connections doctor
kx connections doctor --provider slack --json

For each provider it reports whether the connector binary was found beside your kx executable, found on your PATH, or not found at all — and, when it is missing, the exact cargo install line that builds it from a checkout.

Connect Slack in two commands

kx connections add --provider slack

kx secrets set --name KX_SLACK_CREDENTIAL --value '{"bot_token":"xoxb-…"}'

kx connections fire --name slack --tool list_channels --args '{}'

The other three connect the same way:

kx connections add --provider notion
kx secrets set --name KX_NOTION_CREDENTIAL --value '{"token":"secret_…"}'

kx connections add --provider gmail
kx secrets set --name KX_GMAIL_CREDENTIAL --value '{"client_id":"…","client_secret":"…","refresh_token":"…"}'

kx connections add --provider discord
kx secrets set --name KX_DISCORD_CREDENTIAL --value '{"bot_token":"…"}'

Why two providers can both offer "search"

Slack has a search. Notion has a search. Gmail has a search. They cannot collide, because the runtime namespaces every discovered tool by the connection name you registered it under:

<connection name>/<remote tool name>

So the three land as slack/search, notion/search and gmail/search. The connection name is yours to choose (--name), and it is the half of the id an agent grant is written against. If you register Slack as --name work-slack, the tool is work-slack/search — and an agent must be granted work-slack/search, not slack/search.

Because the namespace is exact, removing a connection is exact too: kx connections remove deregisters everything under that prefix and nothing else.

What "dialing" actually does

When you run add (or discover, or restart the runtime), the sequence is the same one every time:

Reachability has exactly one definition — the full handshake plus tools/list. add, test and discover all run that same probe, so they can never disagree with each other about whether a server is up.

A failed dial is recorded honestly. The connection is stored with health unreachable and 0 tools rather than being silently dropped or reported as a success. Fix the service, then run discover again.

Day-to-day commands

kx connections list                                            # every connection + health + tool count
kx connections test --name slack                               # is it reachable right now?
kx connections discover --name slack                           # re-dial and re-read its tool list
kx connections fire --name slack --tool search --args '{"query":"budget"}'
kx connections remove --name slack                             # drop it and its slack/* tools

list shows each connection's health: connected, unreachable, or unknown before the first dial. Add --json to any of these for a machine-readable form.

Run discover after the service gains or loses a tool. test when you suspect the token expired or the service is down.

Connecting something that is not bundled

Any MCP server works. Give it a name yourself and point at it — a local program over stdio, or a remote endpoint over HTTP:

# a local MCP server you built, spoken to over stdio
kx connections add --name my-tools --command /usr/local/bin/my-mcp-server --arg --stdio

# a remote MCP server over HTTP, refusing plaintext, credential by name
kx connections add --name github \
  --url https://mcp.github.example/rpc \
  --tls-required \
  --credential-ref GH_MCP_TOKEN

The transport is inferred: --command means stdio, --url means HTTP. For HTTP, the credential you store under that name is used as the full Authorization header value, so store it complete (for example Bearer …).

By default each tool call opens its own short session. Pass --stateful (or --session-mode stateful) if the server needs one session reused across calls.

To build your own connector rather than dial someone else's, see Authoring a connector.

Letting an agent use the connection

Registering a connection makes its tools exist. It does not make them fire. A tool fires only when a run's grant names it — presence is never permission.

In an app, declare which connector the app dials, and separately list which tools the agent may fire:

# check the wiring first — this is the operator diagnostic, not an agent run
kx connections fire --name slack --tool read_channel --args '{"channel":"C0123ABCD"}'

import kortecx as kx

app = (
    kx.app("launch-digest")
      .blueprint(
          kx.flow().agent(
              "Summarise the last 20 messages in #launch and post a one-line digest.",
              tools=["slack/read_channel", "slack/post_message"],
          )
      )
      .with_slack()                       # declares the bundled Slack connector
      .secrets(["KX_SLACK_CREDENTIAL"])   # scopes the run to that credential name
)
app.save(handle="apps/local/launch-digest")

import { app, flow } from "@kortecx/sdk";

const launchDigest = app("launch-digest")
  .blueprint(
    flow().agent(
      "Summarise the last 20 messages in #launch and post a one-line digest.",
      { tools: ["slack/read_channel", "slack/post_message"] },
    ),
  )
  .withSlack()
  .secrets(["KX_SLACK_CREDENTIAL"]);

.with_slack() / .withSlack() says this app dials the bundled Slack connector. The agent's tools list says these are the ones it may fire. Grant them by the connection name you registered — slack/read_channel — not by the connector program name.

An agent step needs a model being served by the runtime; kx connections fire does not. See Serving.

Because the app carries only names, an app you hand to a colleague resolves against their connections and their credentials. It carries no authority of its own.

The same idea covers multiple agents: agents chain inside one app, as steps of its blueprint (or with kx swarm --pattern supervisor). One app does not call another app.

When it does not work

A tool call that fails with an authorization error usually means the credential name is set but the value is wrong or expired. Re-run kx secrets set --name … --value … and then kx connections fire … to confirm.

A connection that dialed once and now reports unreachable means the service or the token changed underneath it. kx connections test --name <name> re-checks; kx connections discover --name <name> re-reads the tool list.

If dials are being refused faster than you expect, note that each connection has its own budget: by default a burst of 20 dials per connection, refilling at 10 per second. Repeated add/test/discover in a tight loop will be throttled per server.

Where to go next