Connect an agent over MCP

Any agent that is an MCP client can work in Starlings as you. Claude, Claude Code and Hermes are examples. The agent connects to your workspace's /mcp address, you sign in once, and from then on it reads what you can read and writes only if you allow it.

This is one of two ways an agent works with Starlings:

• Over MCP, as you. Your own agent connects with your access. What it writes is yours and says which client wrote it. This page.
• As a Team agent. A shared agent has its own row in Team, gets messages and cards handed to it, and replies in the thread. See Hand off a card to an agent.

Only a member of this workspace can pair an agent. Starlings has no self-serve workspace yet. The public Starlings site publishes the help pages; use your workspace address for pairing, including /connect and /mcp.

What the client needs

Starlings uses the standard MCP authorization: OAuth 2.1 with discovery, dynamic client registration and PKCE. A client that does these on its own needs only the address.

A client that cannot do OAuth cannot pair. Starlings has no API keys for MCP.

Pair a client

1. Add your workspace's /mcp address to the client as an MCP server. Name it after the workspace, for example Starlings · HQ; the server gives the same name, so two connected workspaces stay apart.
2. The client opens /connect in a browser. Sign in as yourself. To let the agent write, tick Also write before you allow the pairing. Without it, the agent only reads.
3. The client gets its tokens and lists the Starlings tools.

Claude

claude.ai, Claude Desktop and Claude Code each pair this way. See Connect Claude for where to add the connector in each.

Hermes

Hermes is an agent runtime that you run yourself. Add Starlings to ~/.hermes/config.yaml:

mcp_servers:
  starlings:
    url: "<your Starlings origin>/mcp"
    auth: oauth
    oauth:
      client_name: "Hermes"

Then run hermes mcp login starlings. Hermes prints the authorize address and waits for the callback on a loopback port.

An agent on another computer

The redirect goes to loopback: the computer the agent runs on. When that is a server or a Raspberry Pi and your browser is on a different computer, do one of these:

• Paste back. Open the authorize address in your browser and allow the pairing. The browser then fails to load a 127.0.0.1 address. That is expected. Copy the full address from the address bar and paste it where the agent asks for it. Hermes accepts this.
• Forward the port. Run ssh -N -L <port>:127.0.0.1:<port> <user>@<host> with the port the agent listens on, then open the authorize address. The callback reaches the agent through the tunnel.

What the agent gets

The tools: search, open, now, transcript, schedule, start_meeting, send_message, task, create_issue, record_decision, ask_decision, set_goal, cms, docs_write. A read-only pairing lists only the read tools. A workspace that keeps its own records instead of Envisioning's Core does not list cms, and lists create_issue only when Meet's GitHub App is set up for it. The agent also gets the resources and prompts, and an index of the product at /llms.txt.

Start with search or now. Every row has a door; pass it to open.

• ask_decision puts a question in your decision queue when you are not in the conversation (a background or scheduled run). While you are talking with the agent, it asks you there. You answer it from INBOX (Answer a decision).
• task also creates a lead or a project: pass action: "create_lead" or action: "create_project", a title and the organization, by id or by name. A name finds the organization with exactly that name, or creates it. The agent gets the new door and its channel; on a lead, Core posts New Lead Created. The agent can set a lead's five qualification checks, on create or later with update_lead. It cannot delete a lead.
• The agent reads your Quick Notes through now and files one by passing its id as quick_note to task, create_issue, send_message or docs_write; the note is marked filed there, as File… does. It cannot delete a note.
• When you ask, the agent can share a document under /work by link with docs_write: the answer is a link on envisioning.com that the people you send it to can read after they confirm their email. It cannot share a document in another folder, or make one public; share those from Docs.
• The agent can merge duplicate contacts or organizations in Core with cms and merge: Core keeps the oldest, moves everything from the others onto it, and records the merge. The agent names the survivor to you first.

For the full list of what an agent can reach, and what only a person can do, see /features/status.

House standards

Before the agent writes something for people outside your company, such as an offer, a proposal, a case study or website copy, it reads your house standards in Docs: /house/readme and the guide that it names for that kind of document. When you correct the draft, the agent proposes the correction as a new rule in that guide. It edits the guide only after you say yes. After that, every member's agent follows the new rule. The write_offer prompt does this for an offer.

What you see

• A message the agent sends with send_message is yours, and shows a quiet via and the client's name beside the time, so the people reading it can tell. A line the agent leaves in a channel reads, for example, Michell via Hermes recorded a decision.
• When Starlings refuses a call, or the call fails, the agent gets the reason and a suggested next step. A read-only pairing refuses every write. To allow writes, Revoke the pairing and pair again with Also write ticked.
• Starlings records every call. See yours under Settings → Account → Connected Claudes, which lists every MCP client, or all of them on Admin. Revoke ends the pairing.
• Pause stops an agent at its next call and keeps the pairing. Starlings refuses each call and tells the agent that you paused it. Resume lets the next call through. You do not pair again.

Have an agent start a meeting

Ask the agent to start a meeting. It calls start_meeting. This puts the meeting on the calendar, in your own room, and asks your devices to open the room.

Each of your running clients shows Open room or Not now. You have 45 seconds to answer, the same limit as a Wave. The room opens only when you choose Open room. If you do not answer, the meeting stays on the calendar and the room stays closed.

Starlings transcribes a room opened this way, because it is a convened meeting with a title and attendees. Starlings does not transcribe a room opened from a colleague's Call.

For an ordinary calendar event, use schedule. It does not ask your devices and does not open a room.