MCP Server

Connection facts for any MCP client wiring an agent to Halyard. For per-client config, see Connect an agent.

Endpoint

Property	Value
MCP endpoint	https://mcp.usehalyard.ai
Transport	StreamableHTTP (remote HTTP MCP)
Server type	http
Authorization	Bearer-token OAuth 2.0 (not cookies)
Authorization server / issuer	https://api.usehalyard.ai
Protected-resource discovery	https://mcp.usehalyard.ai/.well-known/oauth-protected-resource

Authorization

Step	What happens
Discovery	The client reads /.well-known/oauth-protected-resource to find the authorization server (https://api.usehalyard.ai).
Authorize	On first connection the client opens a browser to sign in and authorize access.
Token	The client receives an OAuth 2.0 access token and sends it as a Bearer token on every tool call.
Context	Each request runs as the authorized user, scoped to that user’s organization. There is no shared/service identity.

Bearer token, not cookies

Halyard’s MCP authorizes with a per-request bearer access token. A session cookie is not sufficient. If whoami fails after connecting, the client is almost always not attaching the bearer token to tool calls — re-run the OAuth flow. See Troubleshooting.

Per-request context

Every tool call resolves the calling user and organization from the bearer token. This is why:

• author: "me" and get_user_profile() (no user_id) resolve to the authorized user.
• Knowledge, events, and team results are always scoped to the caller’s organization.
• Admin-only tools (such as get_delivery_metrics) check the caller’s accessRole.

Blocking limits

Two tools can block while waiting on a human reply over Slack. Both cap the wait.

Tool	Blocking parameter	Max wait
ask_expert	(awaits first reply, automatic)	55s
check_response	wait	55s

If no reply arrives inside the window, the call returns a pending status. Poll again with check_response rather than expecting a single call to block until answered.

Mention URIs

Knowledge entries, people, and other entities are referenced internally with halyard:// URIs (for example, a mention embedded in an entry). Treat them as opaque identifiers — resolve them through tools such as explore_knowledge or get_conversation, not by fetching the URI directly.

Server definition

Minimal HTTP MCP server block:

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

In a client that uses an mcpServers map:

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

Next

• Tool reference — all 29 tools and their parameters.
• Enums & filters — every enum and shared filter.
• Troubleshooting — connection and auth failures.