MCP & agent setup

Your agent's distribution tool.

The MCP server exposes a focused publishing toolset over stdio. Use it with a client that supports local MCP servers.

Works with Claude Code, Claude Desktop, Codex and other clients that can launch a local stdio MCP server. OpenClaw workflows can also call the documented HTTP API. ChatGPT web connectors require a remote MCP transport, which this local setup does not provide.

1. Create an agent key

Open Agent access in the dashboard. Create a named key and save it in your client's secret settings. The key is shown once. No separate user ID is required: the server resolves the authenticated account.

2. Install the MCP server

Requires Node.js 20 or newer. Install the versioned npm package or let npx install it using the client configuration below.

npm install --global @agent-gruvi/gruvi-mcp-server@2.1.0

3. Configure your MCP client

The configuration installs the pinned official Gruvi npm package. Supply your key through the environment rather than chat or a checked-in configuration.

{
  "mcpServers": {
    "gruvi": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@agent-gruvi/gruvi-mcp-server@2.1.0",
        "gruvi-mcp"
      ],
      "env": {
        "GRUVI_API_KEY": "<your-agent-key>",
        "GRUVI_API_URL": "https://api.agentgruvi.com"
      }
    }
  }
}

The local server uses stdio. There is no hosted Streamable HTTP endpoint advertised by this setup.

Codex setup

Add this to your private Codex config.toml. Supply GRUVI_API_KEY through the environment used to launch Codex. Keep the value out of the configuration file.

[mcp_servers.gruvi]
command = "npx"
args = ["--yes", "--package=@agent-gruvi/gruvi-mcp-server@2.1.0", "gruvi-mcp"]
env_vars = ["GRUVI_API_KEY"]
tool_timeout_sec = 180

Official Codex MCP configuration

Publishing access and retries

Setup, channel connections and media preparation do not require a paid plan. Publishing returns PUBLISHING_PLAN_REQUIRED when a plan is needed. Use gruvi_get_plans and gruvi_create_checkout to request a hosted checkout link, then ask the account owner to complete payment.

Respect Retry-After on a 429 response. After a timeout or uncertain send, check delivery status before trying again.

4. Verify the connection

Restart or reload the MCP client, list its tools, then call gruvi_get_user_info and gruvi_get_social_accounts. If authentication fails, check the key and API base URL. A subscription is needed only when submitting a post.

5. Upload, schedule, verify

Call gruvi_upload_video with a local video path and title. It returns a video ID. Select connected account IDs, then call gruvi_schedule_post with a future timestamp.

{
  "videoId": "<uploaded-video-id>",
  "platforms": [
    {
      "platform": "instagram",
      "accountId": "<connected-account-id>"
    },
    {
      "platform": "twitter",
      "accountId": "<connected-account-id>"
    }
  ],
  "scheduledTime": "2026-11-10T18:00:00Z",
  "title": "Your post title",
  "description": "Your caption",
  "tags": [
    "your-tag"
  ]
}

Inspect the returned schedule ID with gruvi_get_scheduled_post. For immediate posts, use gruvi_publish_post and follow with gruvi_get_post_status.

Three-day trial

Eligible verified accounts can start one three-day trial through Stripe-hosted checkout. A payment method is required. The chosen monthly plan renews after the trial unless canceled beforehand. Trial eligibility is checked on the server and cannot be reset by creating another agent key.

Bulk schedules and carousels

Use gruvi_bulk_schedule_videos to schedule up to 20 videos. Use gruvi_upload_carousel for 2 to 10 local images, then gruvi_publish_carousel or gruvi_schedule_carousel. Provide stable request IDs and inspect per-item results before retrying. TikTok defaults to creator-inbox review.

Subscriptions through your agent

Call gruvi_get_plans, let the user choose Starter ($10), Scale ($25) or Pro ($50) per month, then call gruvi_create_checkout with that plan ID and a unique request ID. Return the Stripe-hosted URL for secure payment. Reuse the request ID after an uncertain response. Call gruvi_get_billing_status afterward and wait for an active subscription before sending. The tool does not charge a saved card automatically.

Available tools

Agent operating rules

• Inspect existing media and scheduled posts before repeating an upload or send.
• Publish only with the user's instruction covering the content and destination accounts.
• Treat tokens, signed upload URLs and agent keys as secrets.
• Check delivery status after an uncertain response. Avoid automatic retries that could duplicate a public post.
• Read platform settings before submitting. TikTok defaults to the creator inbox for review.

Discovery resources

llms.txt, full agent guide, OpenAPI 3.1 schema, and the MCP discovery manifest point to this workflow. MCP clients can also read the server's built-in quickstart and API resources.