How to Use the Cosmic MCP in Mastra AI

Q: How do I register Cosmic tools inside a Mastra AI agent?

Instantiate the MCPClient with the Vinkius URL for your Cosmic server. Call listTools() on that client, then spread those tools directly into your Mastra agent configuration block.

Q: Can I require human approval before Mastra AI deletes a Cosmic asset?

Yes, you can configure the requireToolApproval option on your agent. When the agent attempts to run wipecmsobject or wipemediaasset, the workflow pauses until you approve the action.

Build resilient, self-healing Cosmic CMS workflows with Mastra AI and automatic retries.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Cosmic MCP to Mastra AI

Create your Vinkius account to connect Cosmic to Mastra AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Cosmic with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Build resilient pipelines with Mastra AI and this MCP Server

Checking your routing spaces requires `list_bucket_objects` to verify environment paths before creating new drafts. Your agent uses this tool to check the environment routing before triggering `create_cms_object` to provision a new draft. Mastra handles conditional branching natively, so you don't have to write custom retry loops. If a write operation fails, the workflow engine automatically retries with exponential backoff, making sure your headless CMS updates never get lost in transit.

Automate media audits and validation

Auditing files in your media library relies on `get_media_asset` to match explicit media IDs against your records. Your agent calls this tool to inspect files and compares them against active records. If it finds orphaned files, the workflow triggers `wipe_media_asset` to remove them. You can require manual approval for these destructive actions, keeping a human in the loop before files are deleted.

Drop live document rows safely

Purging old content nodes uses `wipe_cms_object` to drop live document rows instantly. This tool clears out deprecated app nodes and removes files from the disk when they are no longer needed. Since this action is irreversible, you'll want to configure Mastra to pause the workflow and request admin approval before the tool executes. This gives you a safety net for critical database modifications.

Setup guide

Set up Cosmic MCP in Mastra AI

Prerequisites

Node.js 18+ and a TypeScript project
@mastra/mcp + @mastra/core packages
Active Vinkius subscription with a valid endpoint token

1

Install dependencies
Run npm install @mastra/mcp @mastra/core plus your preferred model provider (e.g. @ai-sdk/openai).
2

Configure the MCPClient
Create an MCPClient with your Vinkius endpoint as a URL object. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.
3

Discover and inject tools
Call mcpClient.listTools() and spread the result into your agent's tools object. All Cosmic tools become native Mastra tools.
4

Run with any model
Swap openai("gpt-4o") for any AI SDK-compatible provider. Call agent.generate() and the agent routes tool calls through MCP automatically.

agent.ts

import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const mcpClient = new MCPClient({
  id: "cosmic-mcp-client",
  servers: {
    "cosmic-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

const agent = new Agent({
  name: "Cosmic Agent",
  model: openai("gpt-4o"),
  instructions: "You have access to Cosmic tools.",
  tools: {
    ...(await mcpClient.listTools()),
  },
});

const result = await agent.generate(
  "List recent Cosmic transactions"
);
console.log(result.text);

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Cosmic. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Cosmic now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Cosmic MCP in Mastra AI

Instantiate the `MCPClient` with the Vinkius URL for your Cosmic server. Call `listTools()` on that client, then spread those tools directly into your Mastra agent configuration block.

Yes, you can configure the `requireToolApproval` option on your agent. When the agent attempts to run `wipe_cms_object` or `wipe_media_asset`, the workflow pauses until you approve the action.

Mastra AI uses built-in retry mechanisms with exponential backoff. If `list_bucket_objects` hits a rate limit, the client pauses and retries the request automatically without crashing your active pipeline.

Yes, this MCP integration supports both Streamable HTTP and SSE transports. Mastra automatically detects the transport type when you initialize the client with your Vinkius endpoint URL.

Your API keys, schema details, and bucket configurations are protected by a zero-trust architecture. Vinkius hosts the Cosmic MCP Server in an isolated V8 sandbox, meaning your credentials never leak into other workflows.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript