Documentation

Getting Started

Halyard integrates with Claude Code, Claude Desktop, OpenAI Codex, Cursor, Windsurf, and any MCP-compatible AI tool. Once connected, your AI agents can consult human experts in real-time via Slack.

Installation

Choose your AI client below. The MCP server endpoint is:

Claude Code Recommended

Install via the plugin marketplace:

/plugin marketplace add halyard-labs/claude-plugin-marketplace
/plugin install ask-expert@halyard-labs

When prompted, authorize with your Halyard account. The plugin handles OAuth automatically. Claude will then proactively use ask_expert when it encounters ambiguity or needs human judgment.

Enable for your entire team

Instead of having each teammate install manually, add the plugin to your repo's .claude/settings.json. This enables it automatically for anyone who opens the project in Claude Code:

{
  "enabledPlugins": {
    "ask-expert@halyard-labs": true
  },
  "extraKnownMarketplaces": {
    "halyard-labs": {
      "source": {
        "source": "github",
        "repo": "halyard-labs/claude-plugin-marketplace"
      }
    }
  }
}

Commit this file to your repo. Teammates will get the plugin enabled on their next session without any manual setup.

OpenAI Codex

Add Halyard as a remote MCP server in your project's codex.json:

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

On first use, Codex will redirect you to Halyard for OAuth authorization. Codex discovers the available tools automatically.

Claude Desktop, Cursor & Windsurf

Add the following to your MCP client configuration file:

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

Any MCP Client

Halyard exposes a standard Model Context Protocol server over HTTP with OAuth 2.0 authentication.

Point your MCP client at https://mcp.usehalyard.ai. Clients that support RFC 9728 (Protected Resource Metadata) will automatically discover the authorization server via the /.well-known/oauth-protected-resource endpoint.

For manual setup, the authorization server is located at https://api.usehalyard.ai.

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

Configuration

After installing the MCP server, configure your team in the Halyard dashboard.

Experts

Add team members as experts and assign them roles and skills. When an AI agent asks a question, Halyard routes it to the most relevant available expert based on these attributes.

Knowledge Base

Halyard builds an organizational knowledge base from summarized conversations. When an agent asks a question that has been answered before, it can retrieve the answer without contacting an expert. Use the summarize_conversation, search_knowledge, and list_knowledge tools to build and query this knowledge base.

Available Tools

Once connected, your agent gains access to these tools. It will use them proactively when it encounters ambiguity or needs human judgment.

Usage Examples

Architecture Decision

An AI agent needs guidance on authentication strategy while refactoring a login flow.

list_experts(role: "architect")

ask_expert(
  prompt: "Should I use JWT tokens or session-based auth for the new login flow?
           The current codebase uses express-session.",
  role: "architect"
)

check_response(conversation_id: "conv_123", wait: true)

summarize_conversation(
  conversation_id: "conv_123",
  question: "JWT vs session auth for new login flow",
  answer: "Use JWT for the new auth system. Team decided to migrate away
           from sessions for better horizontal scaling."
)

Design Clarification

An AI agent implementing a feature needs to clarify UI requirements with the design team. Provide response options so the expert can quickly tap to respond.

ask_expert(
  prompt: "For the error state on the payment form, should I show
           the error inline or as a toast notification?",
  role: "designer",
  options: [
    { label: "Inline error", value: "inline" },
    { label: "Toast notification", value: "toast" },
    { label: "Both", value: "both" }
  ]
)

The expert sees the options in Slack and can quickly tap to respond, or provide a custom answer.

Multi-turn Conversation

Sometimes you need a back-and-forth discussion with an expert.

ask_expert(
  prompt: "How should I handle rate limiting from the Stripe API?",
  skill: "payments"
)
// Returns: conversation_id: "conv_456"

reply_to_expert(
  conversation_id: "conv_456",
  message: "Should I also add failed requests to a dead-letter queue?"
)

summarize_conversation(
  conversation_id: "conv_456",
  question: "Handling Stripe rate limits",
  answer: "Use exponential backoff + jitter. After 3 retries,
           push to DLQ. Use packages/queue/retry.ts and DLQ helpers."
)

Best Practices

Support

We're here to help you get the most out of Halyard.