Call Hark from the xAI API with remote MCP — guide

xAI's servers connect to Hark on your behalf, so Hark must be reachable publicly (it is) and the call carries your Hark personal access token as a Bearer header.

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client(api_key=os.environ["XAI_API_KEY"])
chat = client.chat.create(
    model="grok-4",
    tools=[
        mcp(
            server_url="https://harkstudio.io/mcp",
            server_label="hark",
            server_description="Shared project memory for my ventures.",
            authorization=os.environ["HARK_TOKEN"],
        )
    ],
)
chat.append(user("List my Hark workspaces, then give me the brief for V-001."))
print(chat.sample().content)

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "input": "List my Hark workspaces.",
    "tools": [{
      "type": "mcp",
      "server_label": "hark",
      "server_url": "https://harkstudio.io/mcp",
      "authorization": "'"$HARK_TOKEN"'"
    }]
  }'

Recommended tool flow for an agent run: list_workspaces → get_agent_brief (or start_session) → the write tools as decisions land → end_session with a handoff.

• allowed_tools (allowed_tool_names in the native SDK) narrows which Hark tools the model may call — useful for a read-only run.
• headers / extra_headers passes any additional headers; authorization is the shortcut for the Bearer token.
• connector_id and require_approval are not supported by xAI's remote MCP.

xAI's remote MCP does not support require_approval, so writes run without a confirmation step. Start with a read-only Hark token (Connections → Tokens) and switch to read + write once you trust the flow.

Grok Build and Grok Bot carry no separate app identity, so Hark labels their activity from the connection: OAuth connections show as Grok Build or Grok, and token-based runs show the token's name — name the token Grok so the activity log reads clearly.

Verify it works

Ask your client: "List my Hark workspaces." Expected: your workspace names.

Then: "Create a project called Connection test in <workspace>." Expected: a new V-### appears in the app and the activity log shows the source ("via Claude Code", "via Codex", etc.). Delete the test venture afterward.

Troubleshooting

• "Unauthorized request origin" — the client origin isn't allowlisted; retry from the latest app version, or email hello@harkstudio.io.
• Consent screen loops / stale token — remove the connector in the client, sign out of Hark, sign back in, re-add the connector.
• Tools list is empty — the connector isn't enabled for this chat (Claude and ChatGPT require enabling it per conversation).
• Plan cap error — you've hit the monthly agent-call cap for this workspace; see billing.
• Old endpoint — anything pointing at a lovable.app URL must be updated to harkstudio.io/mcp.