# Cosmic MCP > Cosmic (Headless CMS & Content API) MCP. Control your content infrastructure, media library, and data structures directly through natural language. This tool lets you build site content, manage image assets, and update object types without ever touching a database console. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** cms-api, content-infrastructure, media-management, api-first, json-api ## Description This connector gives you full control over any modern headless CMS setup. You can treat your entire website's content—the articles, the product listings, the media files—as code that your AI agent controls. Instead of logging into a separate web interface and clicking through menus to make changes, your agent handles everything in conversation. Need to draft a new blog post and update its metadata? Done. Want to delete old images or check which content types exist? No problem. The ability to manage object structures, media assets, and revisions means you're treating your CMS like another service layer right alongside your backend code. Because Vinkius hosts this MCP in the catalog, you can connect it once from any AI client and access all these content operations instantly. ## Tools ### batch_objects Applies a set of changes to multiple objects (up to 25) at once. ### create_media Uploads and creates new media assets, like images or videos, in the bucket. ### create_object Builds a brand-new content object with specified metadata. ### create_object_type Defines and creates an entirely new structure for content objects in the CMS. ### create_revision Adds a specific historical checkpoint or version to any existing object. ### delete_media Permanently removes media files from the content library. ### delete_object Removes a specific, existing content object. ### delete_object_type Deletes an entire template or blueprint for objects in the CMS. ### get_agent_conversation_history Retrieves past messages and actions from a specific AI agent conversation history. ### get_object Fetches the full data record for one object using its unique ID. ### get_object_type Retrieves the specific definition or blueprint for a content type by its slug. ### get_revision Gets the data snapshot of an object at a particular historical point. ### list_agent_conversations Lists all past conversations associated with a specific AI agent user account. ### list_media Shows a list of every media asset currently stored in the bucket. ### list_object_types Retrieves a catalog of all existing content type templates used across the CMS. ### list_objects Lists multiple objects and allows you to filter results using structured query parameters. ### list_revisions Retrieves a list of all available historical versions for a single object. ### send_agent_message Sends a new message directly to an AI agent account, triggering a response. ### update_media Changes metadata—like alt text or descriptions—for existing media files. ### update_object Modifies the content and metadata of an object that already exists. ### update_object_type Makes changes to the blueprint or structure of a content type template. ## Prompt Examples **Prompt:** ``` List the last 5 objects of type 'news' in my bucket. ``` **Response:** ``` I've retrieved the latest 'news' objects. Here are the most recent entries: 'Product Launch' (ID: abc1), 'New Partnership' (ID: abc2), and 3 others. Would you like to see the full content of any of these? ``` **Prompt:** ``` Create a new draft post titled 'AI and CMS' with the type 'blog-posts'. ``` **Response:** ``` Successfully created the draft object 'AI and CMS' (ID: xyz789) in the 'blog-posts' category. You can now add metadata or publish it when ready. ``` **Prompt:** ``` Show me all media files currently in the bucket. ``` **Response:** ``` I found 12 media assets in your bucket. Recent uploads include 'hero-banner.jpg', 'logo-white.png', and 'intro-video.mp4'. Do you need the URL for any specific file? ``` ## Capabilities ### Drafting new site objects Create completely new pieces of structured content (like a blog post or product listing) with specific metadata. ### Retrieving existing data records Fetch specific content items, list multiple results, or check an object's full revision history by ID. ### Handling media assets Upload new images and videos, delete old ones, or update the metadata attached to existing files in the library. ### Structuring content types Programmatically create, read, and update the blueprints that define what kind of data you can store (the object types). ### Running bulk updates Apply changes to up to 25 different objects in a single request for high-efficiency maintenance. ## Use Cases ### A marketing team needs to roll out a campaign landing page. The manager asks their agent: 'Draft five new articles about Q3 earnings, using the 'news' object type.' The agent responds by executing `create_object` for all five drafts and then calls `list_media` to confirm that the required hero banner is present. ### A developer needs to update metadata across thousands of records. Instead of writing a complex script, they tell their agent: 'Update the SEO title for all objects in the 'product' type that haven't been touched this month.' The agent uses `update_object` and `list_objects` to execute the mass change. ### A product team needs to audit old content. The PM asks: 'Show me all objects of type 'legacy-product' that have never been viewed in 90 days.' The agent runs `list_objects` with a complex query and flags the records for archival. ### A tech writer needs to ensure new content adheres to standards. The writer tells the agent: 'I need to create an object, but first check if the required image type exists.' The agent uses `list_object_types` and then calls `create_object` only after validation. ## Benefits - You don't have to switch context. With this MCP, you can draft a new object and immediately check its associated media library using `list_media`—all from your agent chat window. It keeps the workflow contained. - Avoid data silos by automating updates. Need to update 20 product descriptions? Use `batch_objects` to push changes across multiple records in one go, saving hours of manual API calls. - Maintain content integrity with full visibility. Check object history using `get_revision` or review the past actions via `list_revisions`. You always know who changed what and when. - Build flexible data models on demand. If you need a new kind of data (say, 'Testimonials'), use `create_object_type` to build its blueprint before content even gets written. - Manage media alongside text. Use `update_media` to change an image's alt tag immediately after creating the accompanying object using `create_object`. ## How It Works The bottom line is that you give your AI client the necessary keys and context; it handles all the complex CMS calls for you. 1. First, subscribe to this MCP and provide your Cosmic Bucket Slug, Read Key, and Write Key credentials. 2. Next, point any AI client—like Cursor or Claude—to the Vinkius catalog connection. Your agent now has access to all content tools. 3. Finally, ask your agent to perform a task: 'Create an object called X with this metadata,' or 'List all media assets in the bucket.' ## Frequently Asked Questions **How do I list all available media with the Cosmic API?** You use the `list_media` tool. This function shows every asset currently in your bucket, letting you find specific files or count how many assets are ready for deployment. **What if I want to change an object's metadata but not its content?** Run `update_object`. This tool lets you modify the surrounding data—like changing a 'featured' flag or adjusting the last modified date—without touching the core body text. **Can I view how an object looked six months ago using get_revision?** Yes. The `get_revision` tool lets you pull a historical snapshot of any content object, letting you audit past versions before making changes today. **What is the best way to update multiple objects at once? Should I use update_object repeatedly?** No. Use `batch_objects`. This tool lets you group up to 25 object updates into a single call, which is much faster and more efficient than running 25 separate operations. **When using `list_object_types`, how do I see all the available content structures in my Cosmic bucket?** It lists every defined object type in your connected bucket. This allows you to query which specific content schemas exist, helping you target your data operations accurately before attempting to read or write objects. **I need to remove an old schema; what is the process for using `delete_object_type`?** You execute `delete_object_type` with the specific slug of the type you want gone. Be careful, because this action permanently removes the structure and prevents future objects from being created under that name. **When using `list_objects`, what format do I provide for the query parameter to filter content results?** You must pass a URL-encoded JSON object within the query parameter. This lets you precisely limit the list of objects based on specific metadata fields, rather than retrieving everything in the bucket. **If I only want to change an image's title or tags, should I use `update_object` or `update_media`?** Use `update_media`. This tool lets you manipulate the metadata associated with a media asset—like changing its description or adding tags—without needing to re-upload the physical file itself. **Can I filter objects by a specific type like 'blog-posts'?** Yes! Use the `list_objects` tool and provide a JSON query string like `{"type":"blog-posts"}` in the query parameter to filter your results. **How do I update the content of an existing object?** You can use the `update_object` tool. Provide the Object ID and the new values for `title`, `metadata`, or `status` to modify the entry. **Is it possible to see who made changes to an object?** Yes, you can use the `list_revisions` tool for a specific object to see its history, and `get_revision` to inspect the details of a specific version.