Huddled for AI agents

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

Huddled is a private place for a group to share photos and videos 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 the owner grants. The grant is enforced on every call.

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

https://api.huddled.cloud/mcp

You do not need an API key. The server is an OAuth 2.1 authorization server. A compliant MCP client (Claude Desktop, Claude Code, and others) completes the flow automatically:

  1. Add the URL above as an MCP server in your client.
  2. The first call returns 401 with a WWW-Authenticate header that points at the discovery document. Your client reads it, registers itself (Dynamic Client Registration), and opens a browser.
  3. The organization owner approves the grant on Huddled's consent screen. They choose:
    • which organization to grant,
    • which Spaces (all, or a subset),
    • the role you act as (Viewer, Contributor, or Admin),
    • the exact permissions (scopes).
  4. Your client receives a long-lived access token and stores it. Every later call authenticates automatically.

The handshake is standard OAuth 2.1 with PKCE. Your client implements it, not you. There is nothing to copy or paste.

Example client config

Most clients only need the URL:

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

What you can do

The server offers these tools. Each needs a scope. If the owner did not grant a scope, that tool 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 and videos across Spaces.
create_space spaces:write Create a new Space in the organization.
upload_media media:write Upload a photo or video 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 reads Space names and metadata.
  • spaces:write creates and modifies Spaces.
  • media:read searches and reads media.
  • media:write uploads media.
  • comments:write posts comments.
  • reactions:write posts reactions.
  • members:write invites and manages members.
  • activity:read reads the activity feed.

Your effective permissions are the intersection of the granted scopes, your role, and the granted Spaces. A 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 (the API keys page under Developers in the Huddled app). Send it as a bearer token on every request:

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

The same key works against the REST API at https://api.huddled.cloud/v1. OAuth tokens and API keys resolve to the same scoped credential. Use whichever your client supports.

Requirements and good behavior

  • A paid organization. Agent access requires the owner to be on a Pro or Team plan.
  • The owner is in control. They can revoke your access at any time on the Authorized agents page under Developers. After that, your next call returns 401. Re-run the connect flow only if they ask you to.
  • Stay within scope. Do not attempt tools you were not granted. Prefer read-only operations unless the task clearly needs a write.
  • Respect rate limits. Requests are rate-limited per credential. Back off on 429 responses.