Skip to content
Halyard Docs Halyard Docs Halyard Docs

Quickstart

By the end of this you’ll have one AI client connected to Halyard and an agent that can search the knowledge base, ask a human expert, and capture the answer.

This is the path for connecting an agent. It assumes a Halyard workspace already exists with Slack connected and at least one expert added — if you own that setup, do Set up your workspace first.

Connect a client

Section titled “Connect a client”

You have two ways to point a client at Halyard. Pick one.

Option A — Halyard CLI (fastest for a repo)

Section titled “Option A — Halyard CLI (fastest for a repo)”

From the root of a repository, run:

Terminal window
pnpm dlx @halyard/cli init

The CLI writes MCP config for the AI clients it detects (Claude Code, Cursor, Codex). It does not start the OAuth flow itself — restart or reload the client afterward and it will prompt you to authorize.

Option B — Remote MCP server (any client)

Section titled “Option B — Remote MCP server (any client)”

For any client that supports a remote HTTP MCP server, add this block to its MCP config:

{
  "mcpServers": {
    "halyard": {
      "type": "http",
      "url": "https://mcp.usehalyard.ai"
    }
  }
}

Authorize

Section titled “Authorize”

Start or reload the client. On first connection it opens an OAuth flow in your browser. Sign in at app.usehalyard.ai and grant the client access. After authorizing, the client calls Halyard tools as your user, in your organization.

Verify

Section titled “Verify”

Ask the agent to run whoami. A healthy response identifies your user and organization and lists what’s connected:

{
  "status": "success",
  "user": {
    "email": "you@acme.com",
    "name": "Jordan Lee",
    "accessRole": "ADMIN",
    "roles": ["product manager"]
  },
  "organization": { "name": "Acme", "slug": "acme", "memberCount": 8 },
  "connections": {
    "channels": [{ "type": "SLACK", "verified": true }],
    "integrations": [{ "provider": "github", "name": "GitHub installation 1234567" }],
    "linked_accounts": [{ "provider": "slack" }, { "provider": "github" }]
  },
  "authenticated_via": { "type": "oauth", "clientName": "Claude" }
}

If whoami fails, the bearer token usually isn’t reaching the server — see Troubleshooting.

Run the loop

Section titled “Run the loop”

Now exercise the full loop in one prompt. Ask the agent:

Search Halyard for prior decisions about how we ingest calendar data. If
nothing useful turns up, ask an engineer who knows the area, then summarize
whatever answer you get back into Halyard.

The expected tool sequence is:

  1. search_knowledge — checks the knowledge base first.
  2. ask_expert — only on a miss; routes the question to a matching expert in Slack. (If the knowledge base already holds the answer above the similarity threshold, this step returns it directly instead of paging a human.)
  3. summarize_conversation — writes the answer back as a knowledge entry for the next agent.

Next

Section titled “Next”