Hubert MCP server

Quick start #

Sign-in needs a Hubert account. Create one for free at app.hubert.team.blue/en/hub/signup. Without an account, tools return ACCOUNT_SETUP_REQUIRED.

list_brands and search answer without a token, so an agent can probe the server before the user signs in. Without a token, search shows only what needs no account.

Claude

1. Open Settings → Connectors → Add custom connector.
2. Paste the server URL: https://mcp.hubert.team.blue/central/mcp
3. Complete the OAuth sign-in when prompted. You approve access once; the connection persists.
4. Ask for a post. See the example prompts.

ChatGPT

1. Open Settings → Connectors → Create.
2. Paste the server URL: https://mcp.hubert.team.blue/central/mcp
3. Choose OAuth as the authentication method and complete sign-in.

Any MCP client

{
  "mcpServers": {
    "hubert": {
      "type": "http",
      "url": "https://mcp.hubert.team.blue/central/mcp"
    }
  }
}

Local / stdio

For clients that start the server as a local process:

MCP_TRANSPORT=stdio node dist/index.js

How it works #

Your assistant never talks to the social networks directly. It calls Hubert, which holds the user's connected accounts and forwards the action to the team.blue Hub API. The assistant signs in to Hubert once, over OAuth 2.1.

The assistant sees only the tools listed below. It cannot reach the Hub API by any other route, and it cannot act for anyone who has not signed in.

The posting flow #

At initialize, Hubert returns instructions that set the order of the steps below. Several tools are stateful: if a step is skipped, the tool returns a recoverable error.

1. Sign in. With OAuth this happens outside the chat. Never ask the user for an email address or a code. If a result says the account needs setting up, present the returned action, wait for the user to confirm they are done, then retry.
2. Compose. ig_compose_start starts the composer. Called with no topics, it returns four post ideas based on the user's business. Call it again with exactly one topic, either one of those ideas or the user's own wording, to generate the caption and image. The image is a stock photo (Unsplash or Pexels), never AI-generated. Clients that support MCP Apps can also show an interactive composer, but do not assume it rendered. Do not tell the user to open a separate Hubert page unless a tool returns an explicit URL.
3. Connect, if needed. Call metricool_social_status to check. If Instagram is not connected, call metricool_social_connect and present the returned link with the label "Connect Instagram". Poll metricool_social_status and continue automatically once it succeeds.
4. Confirm. Show the final caption, image, post type and publication time. Never call a publishing tool before the user explicitly approves.
5. Publish and verify. Call the publishing tool with confirmed: true, then check metricool_scheduled_posts_list to report the real state.

There are two separate setup gates. ACCOUNT_SETUP_REQUIRED means the user has no provisioned team.blue business account. Nothing can proceed until the user completes the returned set-up action. A metricool_social_status result with no connected account means the business exists but has no Instagram account linked; metricool_social_connect fixes that. Resolving one gate does not resolve the other.

Two more rules:

• Keep the conversation user-facing. Do not mention internal systems or tool names unless the user asks for implementation details.
• Only describe Hubert as unavailable on SERVICE_UNAVAILABLE or a genuine network/5xx result. Never infer an outage from a 404.

Authentication #

Hubert authenticates with OAuth 2.1. The server is an OAuth-protected resource; your client discovers the authorization server from the standard protected-resource metadata document and runs the authorization-code flow with PKCE.

Every brand action except health requires a valid bearer token. Calling an authenticated one without a token returns SIGN_IN_REQUIRED. On the Central URL, list_brands and search also answer without a token.

Identity resolves from the token subject. There is no per-brand allow-list on the server. Anyone who completes sign-in can use it, and can act only on what their own account owns.

There is no auth-start tool on the OAuth path. If a session expires mid-conversation, the client handles re-authentication: tell the user and let the connector sign them in again. The expired status and the auth-start guidance in the status table apply to the local OTP flow only.

Tools #

The hosted URL exposes five Central tools (see The Central server). The tools below are the brand actions that search returns and the three execute_* tools run.

Tools marked worker are called by Hubert's embedded composer widget. They are listed for completeness; the model should not call them.

Composing

The composer returns the generated caption and image for review. Those are the values you pass as text and image_url when publishing. Read them from the tool result instead of hard-coding field names, because the response shape may still change.

Publishing

The hosted server publishes to Instagram only. Facebook is used only to connect an Instagram Business account; there is no Facebook post tool.

Accounts

Reading and utility

Hubert publishes these groupings as MCP annotations: writeTools (everything that changes state), destructiveTools (the three marked above), and openWorldTools (the two publishing tools, which reach systems outside team.blue).

Response envelope #

Every tool returns a structuredContent object with a status. The calling model should branch on that status, using the table below.

{
  "structuredContent": {
    "status": "action_required",
    "code": "ACCOUNT_SETUP_REQUIRED",
    "action": {
      "type": "open_url",
      "label": "Connect Instagram",
      "url": "https://..."
    },
    "resume_original_request": true
  }
}

Fields you may also receive: next_tool and retry_tool name the exact tool to call next; retryable is a boolean on error envelopes.

Neither field is always present. When a status tells you to retry, use retry_tool if it is there, otherwise next_tool, and if neither is given re-issue the original call with the same arguments.

Treat an unrecognised status as terminal and report it to the user.

Errors #

Transport-level: a non-POST request to the MCP endpoint returns JSON-RPC error -32000, "Method not allowed. Use POST for MCP requests."

A 404 means a specific resource is missing. It does not mean Hubert is down.

Rate limits #

60 requests per 60 seconds, counted in fixed windows.

Requests are counted per authenticated subject once a bearer token has been verified, and per IP address for anonymous calls. Exceeding the limit returns HTTP 429, surfaced as RATE_LIMITED with status retry_later.

The limiter runs in memory in each container and is not shared between instances. With several instances running, each one allows 60 requests per window.

Safety and limits #

No tool deletes published content. The server has no delete tool, so the worst a successful prompt injection can do is publish an unwanted post. The limit comes from which tools exist, so no prompt can lift it.

Two tools are annotated destructive: metricool_social_disconnect and metricool_social_resolve_duplicate. They disconnect or move an Instagram account. Neither of them removes published content.

Publishing tools require confirmed: true. Set it only after the user has seen and approved the exact text and image.

What Hubert cannot do:

• Delete published content
• Publish anything without confirmed: true
• Reach accounts the user has not connected
• Read private messages

Example prompts #

• "Post something about our new opening hours to Instagram."
• "Which social accounts do I have connected?"
• "Write an Instagram post announcing we're hiring a pastry chef."
• "What have I got scheduled this week?"
• "Give me a few post ideas for this week."

The Central server #

Hubert is served through Central, team.blue's portfolio surface, at https://mcp.hubert.team.blue/central/mcp. Central routes a request to the right team.blue brand without loading every brand's tools into context. Hubert is currently the only onboarded brand. It exposes five tools:

• list_brands: first step. Lists the onboarded brands, your access state and each brand's entry points.
• search: second step. Matches the user's request to a brand action and returns the routing values, input schemas and safety flags.
• execute_read: runs a brand action that only returns information, such as a status check or a listing.
• execute_write: runs a brand action that creates or changes something, from drafting a caption to publishing a post. Publishing needs the user's explicit approval (confirmed: true).
• execute_destructive: runs a brand action that removes or disconnects something. Ask the user first and pass confirmed: true only after approval.

Support #

• Email: hubert@team.blue
• Site: hubert.team.blue