Troubleshooting
Use this when the integration is installed but the agent can’t use Halyard correctly.
The client can’t see Halyard tools
Section titled “The client can’t see Halyard tools”| Check | Fix |
|---|---|
| Server URL | Must be exactly https://mcp.usehalyard.ai. |
| Server type | http (remote StreamableHTTP), not a local command. |
| Config location | The file must be where your client actually reads MCP config. |
| Restart | Restart the client after editing MCP config. |
Then ask the client to list tools, or call whoami. See MCP server for the canonical server block.
OAuth won’t open
Section titled “OAuth won’t open”| Check | Fix |
|---|---|
| Client support | Confirm the client supports remote HTTP MCP servers with OAuth. |
| Re-add | Remove and re-add the MCP server config, then restart. |
| Sign-in works | Verify you can sign in directly at app.usehalyard.ai. |
| Manual setup | If the client needs the authorization server explicitly, use https://api.usehalyard.ai. Discovery is at /.well-known/oauth-protected-resource. |
whoami fails
Section titled “whoami fails”whoami takes no arguments, so a failure is an auth problem, not a parameter problem.
| Cause | Fix |
|---|---|
| Bearer token not sent | Halyard authorizes with a per-request bearer access token, not a cookie. Re-run the client’s OAuth flow so the token attaches to tool calls. |
| Wrong workspace | You authorized a different Halyard org than expected. Re-run OAuth and confirm the workspace. Check whoami → organization.name. |
See MCP server → Authorization.
ask_expert finds no one
Section titled “ask_expert finds no one”Over-constraining is the most common cause. Diagnose by widening filters.
| Check | Fix |
|---|---|
| Role exists | Does anyone have the requested role? Roles are lowercase free text (engineer, pm). |
| Skill exists | Does anyone have the requested skill? Skills are Title-Case (React, System Design). |
| Both passed | Passing role and skill narrows hard. Drop one. |
| Availability | availability is model-only and not in the UI — don’t assume it’s filtering people out, but it can. |
Call list_team with no filters to see the real roles, skills, and availability before retrying. Remember Slack is the only live notification channel — if no one is reachable there, ask_expert returns a KB-only or pending result.
Search results are weak
Section titled “Search results are weak”Search quality tracks what’s been summarized.
| Cause | Fix |
|---|---|
| Thin knowledge base | Summarize useful expert answers (summarize_conversation) and meaningful work (summarize_work). |
| Vague queries | Use concrete system names and domain terms, not “bug fix” or “decision”. |
| Stale guidance | Mark superseded entries so newer guidance wins (supersedes_entry_id). |
| Too tight | Lower threshold (default 0.55) or drop type / author / since filters and retry. |
| Wrong substrate | Looking for activity, not knowledge? Use list_events — work events are not semantically searchable. |
Agents ask humans too often
Section titled “Agents ask humans too often”Tighten project instructions so the agent searches first:
Search Halyard knowledge before asking a human. Use ask_expert only forunresolved, team-specific judgment, and summarize useful answers.Then test with a prompt that should hit existing knowledge.
Agents never ask humans
Section titled “Agents never ask humans”The opposite failure. Tell the agent which uncertainty types require Halyard:
Use Halyard for product intent, historical decisions, ownership questions,and architecture conventions that are not obvious from the repo.A good agent searches first, then asks when the answer is genuinely absent or ambiguous.