Huddled for AI agents

This page tells an AI agent exactly how to connect to Huddled and act inside a user's Spaces. If you are an autonomous agent reading this: follow the Connect steps below, then use the tools listed under What you can do.

Huddled is a private place for a group to share photos, videos, and files inside Spaces. An organization owner grants you access to some or all of their Spaces, with a role and a set of permissions (scopes). You can never do more than what the owner grants — the grant is enforced on every call.

Huddled exposes a Model Context Protocol server over streamable HTTP. Point your MCP client at:

https://api.huddled.cloud/mcp

You do not need to be handed an API key. The server is an OAuth 2.1 authorization server, so a compliant MCP client (Claude Desktop, Claude Code, and others) will do this automatically:

  1. You add the URL above as an MCP server in your client.
  2. On the first call, the server responds 401 with a WWW-Authenticate header pointing at its discovery document. Your client reads the discovery metadata, registers itself (Dynamic Client Registration), and opens a browser.
  3. The organization owner lands on Huddled's consent screen and chooses:
    • which organization to grant,
    • which Spaces (all, or a specific subset),
    • the role you act as (Viewer, Contributor, or Admin),
    • the exact permissions (scopes) you may use.
  4. After they approve, your client receives a long-lived access token and stores it. Every subsequent MCP call is authenticated automatically.

The whole handshake is standard OAuth 2.1 with PKCE — you do not implement any of it yourself; your MCP client does. There is nothing to copy or paste.

Example client config

Most clients only need the URL; they discover and complete OAuth on their own:

{
  "huddled": {
    "url": "https://api.huddled.cloud/mcp"
  }
}

What you can do

The server exposes these tools. Each requires a scope; if the owner didn't grant a scope, that tool is filtered out and never appears in your tool list. Write tools never appear for a read-only grant.

Tool Scope What it does
list_spaces spaces:read List the Spaces you can access.
get_recent_activity activity:read Recent uploads, comments, and joins.
search_media media:read Find photos, videos, and files across Spaces.
create_space spaces:write Create a new Space in the organization.
upload_media media:write Upload a photo, video, or file to a Space.
add_comment comments:write Comment on a media item.
react reactions:write Add a reaction to a media item.
invite_member members:write Invite someone to a Space.

Scopes reference

  • spaces:read — read Space names and metadata.
  • spaces:write — create and modify Spaces.
  • media:read — search and read media.
  • media:write — upload media.
  • comments:write — post comments.
  • reactions:write — post reactions.
  • members:write — invite and manage members.
  • activity:read — read the activity feed.

Your effective permissions are the intersection of the scopes granted, the role you act as, and the Spaces you were given. A tool call outside that boundary is rejected.

Manual alternative (API key)

If your client does not support OAuth, the owner can create an API key instead (Developers → API keys in the Huddled app) and hand it to you. Send it as a bearer token on every request:

{
  "huddled": {
    "url": "https://api.huddled.cloud/mcp",
    "headers": {
      "Authorization": "Bearer hk_live_..."
    }
  }
}

The same key also works against the REST API at https://api.huddled.cloud/v1. OAuth and API keys are equivalent under the hood — both resolve to the same scoped credential — so pick whichever your client supports.

Requirements & good behavior

  • A paid organization. Granting agent access requires the owner to be on a Pro, Ultra, or Enterprise plan. On the Free plan there is no one to authorize you.
  • The owner is in control. They can revoke your access at any time under Developers → Authorized agents. When they do, your next call returns 401 and you should re-run the connect flow only if they ask you to.
  • Stay within scope. Don't attempt tools you weren't granted; they won't be offered. Prefer read-only operations unless the task clearly calls for a write.
  • Respect rate limits. Requests are rate-limited per credential; back off on 429 responses.