Team connectors
Register an OpenAPI spec, GraphQL endpoint, or remote MCP server for your team, connect an account, decide what agents may call, and run tools
Private BetaA connector is a source of tools that a team registers once: an OpenAPI spec, a GraphQL endpoint, or a remote MCP server. A connection is one account on that connector. Agents get the tools. The credential stays in Spacefast, and no endpoint ever returns it.
Connectors are in Private Beta. A team without access gets feature_unavailable.
Before you start
- Only team owners and admins can open the connectors pages. A member sees Only Team Owners and Admins Can Manage Connectors.
- An API key needs connector scopes.
connectors:readreads everything.connectors:writeregisters connectors, connects accounts, and sets policy.connectors:executeruns tools.writeandexecuteboth includeread, but neither includes the other. See API keys.
The pages live under Connectors in the team sidebar. A switch in the header moves between Connectors, Runs, and Policies.
Add a connector from the catalog
The catalog lists curated presets, the public registry, and your team’s own connectors. It has one row per surface, so a service with an API and an MCP server is two rows.
- Open Connectors in the team sidebar.
- Click Browse Connectors.
- Search, or filter by All, API, GraphQL, or MCP.
- Click Add on the row you want.
The row changes to View when the connector exists. A row that needs a provider-specific endpoint shows Set Up instead of Add, and opens the add form.
From the CLI, pass a catalog slug:
sf connectors create linear
Add a connector from a URL
Paste any URL the service published. Detection looks behind it, so the URL it registers can differ from the one you pasted.
- On Browse, paste the URL into the search box.
- Click Detect.
- Click Add Connector on the candidate you want.
- Check Name, Namespace, and Description.
- Click Register.
Namespace is the connector slug. It takes lowercase letters, digits, and dashes, and starts with a letter or a digit. Every tool address of the connector starts with it. Agents read Description when they choose between connectors.
You enter no credential here. Authentication comes from the source. Spacefast asks an MCP server how it authenticates, so a server that wants OAuth gets an OAuth connector.
sf connectors detect https://api.example.com
sf connectors create https://api.example.com/openapi.json
Connect an account
- On Connectors, open the connector row.
- Click Connect Account.
- Under Who can use it, choose Team or Personal.
- If the connector offers more than one method, choose one under Method.
- Optional: enter a Label. Agents see it when a connector has more than one account.
- Click Connect.
Team shares the account with everyone on the team and every agent that acts for it. Personal keeps it yours, and only within this team. An API key can connect Team accounts only.
Connecting ends in one of three ways:
| Result | What to do |
|---|---|
connected |
Nothing. The account is ready |
authorization_required |
Sign in at the provider. In the dashboard, click Open Sign-In. The CLI prints the URL. The callback finishes the connection, so there is nothing to paste back |
input_required |
Give the values the connector asks for, then connect again |
For an input_required answer, the dashboard shows each field with the provider’s own help when the registry has some: setup notes, steps, a Create one link, and a Provider docs link. The CLI prints the same help under each --field. The same help is available from getConnectorCredentialGuidance.
sf connectors connections connect stripe --api-key "$STRIPE_KEY"
sf connectors connections connect linear --owner personal
A tool address is <connectionId>/<tool>. While exactly one usable account matches, <connector>/<tool> also works. Connect a second account and the short form fails with connection_ambiguous, so use the connection id. No account is the default once a connector has two.
Keep a connection working
Open a connector, then the Accounts tab. Each account has an actions menu.
| Action | What it does | CLI |
|---|---|---|
| Edit… | Changes the Label and the agent note, What it’s for | sf connectors connections update |
| Check Health | Probes the provider and reports what came back. It changes nothing | sf connectors connections health |
| Re-Sync Tools | Reads the tool list again, so new or dropped tools show up | sf connectors connections refresh |
| Reconnect… | Signs in again, or replaces the key. The account keeps its id, label, policies, and Space bindings | sf connectors connections reconnect |
| Disconnect… | Destroys the stored credential. Anything that uses the account stops working | sf connectors connections disconnect |
An account in needs_reauth or degraded also shows a Reconnect button. Token refresh happens on its own, so reconnect only when the status asks for it.
Credentials cannot be edited. To rotate a key, reconnect the account. A disconnected account cannot be reconnected. Connecting the service again makes a new account with a new id.
Decide what agents can call
A policy rule pairs an address pattern with an action.
| Pattern | Matches |
|---|---|
* |
Every tool |
<connector>/* |
Every tool on every account of one connector |
<connector>/<tool> |
One tool on every account of one connector |
<connectionId>/* |
Every tool of one account |
<connectionId>/<tool> |
One tool on one account |
| Action | Dashboard label | When an agent calls a matching tool |
|---|---|---|
approve |
Runs freely | The call runs |
require_approval |
Ask first | The run parks until a person decides |
block |
Blocked | The run fails with connector_tool_blocked |
How rules combine:
- The most specific pattern wins. Spacefast orders rules by specificity, not by the order you add them.
- A Team rule is a floor. A Personal rule can tighten it but never loosen it.
- When no rule matches, the tool’s own default from its source applies. A tool can also ask for approval on its own.
- A rule’s pattern and owner are fixed. To change either, delete the rule and add a new one.
- Deleting a rule hands its tools to the next matching rule. Deleting a block can open a tool again.
To add a rule:
- Click Policies in the connectors header.
- Type a Pattern. The hint below it counts the tools it matches today.
- Choose an action under Then.
- Choose Team or Personal under Applies to.
- Click Add Rule.
A pattern that names an unknown connector or connection is refused. An API key can add Team rules only.
To check one address without calling it, run sf connectors policies explain. It prints the effect, the rule that decided it, and the reason. The API equivalent is resolveConnectorPolicy.
sf connectors policies add '*' --action require_approval
sf connectors policies explain cxn_abc123/charges.create
Find a tool
Click See tools on a connector row, or open Connector tools from the command palette. The Tools page lists every tool the team’s accounts reach. Each row shows the tool name, its summary, its resolved effect, and its safety: Read-only, Writes, or Destructive. Safety comes from the source and is not a setting.
Open a tool to see its address, the rule that decided its effect, and its Input schema. The API equivalents are listConnectorTools and listConnectionTools.
Run a tool
To try a tool yourself, open it on Tools, fill in Arguments as a form or as JSON, and click Run. Your run follows the same policy an agent gets.
From the CLI, pass the tool address and its arguments:
sf connectors run --tool cxn_abc123/issues.list --args '{"limit":5}'
A run is one tool call, or a program that calls several tools. Both get one run id (cxr_…) and the same statuses.
| Status | Meaning |
|---|---|
running |
Still working. Read it again with sf connectors run inspect |
awaiting_approval |
Parked on a decision |
succeeded |
Done. The result is in result |
failed |
Done. The reason is in error, a problem document |
expired |
Parked too long. Submit it again |
The request waits up to 30 seconds for a final status by default. Set --wait to change that, up to 120 seconds. A failed run is still a successful request, so read the run’s status before you report success. The CLI exits 1 for a failed or expired run.
Decide a parked run
A parked run carries an approvalUrl that opens the dashboard on the decision. You can also find it in two places:
- Approvals, under Connector calls awaiting approval.
- Runs, with the Waiting on you filter. Click Review to see the rule, the arguments, and the deadline, then approve. Deny sits on the row.
Approve runs the call once. Deny fails the run with connector_tool_blocked. A run left parked for 15 minutes expires.
A run parks for a person. A CLI login or an API key cannot approve it, and an attempt fails with human_approval_required. After a person decides, read the outcome with sf connectors run inspect.
To fail fast instead of parking when nobody is watching, pass --deny-unattended. The run then fails with connector_approval_required.
Let an agent use connectors
On-device MCP, sf mcp, has one gateway tool, search_connector_tools. It searches the team’s connected services, calls a tool, and resumes a parked call. Hosted MCP and sf mcp proxy do not offer it, and they have no connector operation tools. See MCP server.
The CLI and the connectors API give an agent everything else.
Use a connection in a Space
To show a connection’s data on a Space’s pages, declare a role and bind the connection to it. See Connectors.
Remove a connector
sf connectors delete linear --yes
Removing a connector disconnects every account on it, then deletes the connector and its tools. Built-in connectors cannot be removed.