# JSONBin.io MCP

> JSONBin.io connects your AI agent to cloud-based storage for structured data. It lets you create, manage, and query complex JSON datasets—think of it as a persistent scratchpad for your AI workflow. Need to store API mock results or maintain session state? This MCP handles everything from basic record creation to advanced version tracking using powerful JSON Path queries.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** json-storage, nosql, api-testing, data-persistence, cloud-database

## Description

Look, sometimes your AI agent needs more than just the chat history; it needs reliable data storage. With this MCP, you turn your client into a genuine data management assistant. You can treat your AI workflow like a small application backend, storing configurations or processing results in persistent bins. Need to prototype an API that spits out JSON? Just create a bin and let your agent work with it. The best part is the structure: you manage collections for organization, track every change using versioning, and even use advanced querying methods—like filtering data using JSON Path—to grab only what you need from massive datasets. Because Vinkius hosts this MCP, you connect once to your AI client and get access to all these powerful data structures.

## Tools

### add_schema_to_collection
Adds a defined JSON schema document to an existing collection so its contents can be validated.

### count_bin_versions
Returns the total number of versions stored for a specific JSON bin, useful for auditing data changes.

### create_access_key
Generates a new, restricted access key that limits what an agent can do with your bins.

### create_bin
Creates a brand new JSON bin containing the specific data you provide.

### create_collection
Establishes an organized container to hold multiple related bins together.

### create_schema
Creates a formal JSON schema document that defines the required structure for your data.

### create_xl_bin
Generates an XL bin, allowing you to store large datasets up to 10MB of complex JSON.

### delete_access_key
Removes a specific access key, immediately revoking its ability to interact with your data.

### delete_all_bin_versions
Wipes out all historical versions associated with a given JSON bin.

### delete_bin
Permanently removes an entire JSON bin and all its contents.

### delete_xl_bin
Removes a large XL JSON bin from your account.

### download_usage_logs
Downloads usage activity logs for bins, restricted to a specific date range.

### fetch_collection_bins
Retrieves a list of all the individual JSON bins that belong within a specified collection.

### fetch_uncategorized_bins
Lists all JSON bins that haven't been assigned to any specific organizational collection yet.

### list_access_keys
Shows a list of every access key currently active on your account.

### list_collections
Retrieves the names and IDs of all collections you have created.

### list_usage_log_dates
Returns a list of available dates for which usage logs can be downloaded.

### read_bin
Reads the data from an existing JSON bin, and lets you optionally filter it using JSON Path syntax.

### read_schema
Retrieves the content of a defined JSON schema document for review.

### read_xl_bin
Reads and downloads the contents of a large XL JSON bin.

### remove_schema_from_collection
Deletes a specific schema definition that was previously linked to a collection.

### update_bin_name
Changes the visible name of a specific JSON bin without altering its contents.

### update_bin_privacy
Adjusts whether a particular bin is public or restricted to certain users.

### update_bin
Modifies the existing JSON data within an already created bin.

### update_collection_name
Renames an entire collection of related bins for better organization.

### update_schema_name
Changes the display name of a specific JSON schema document.

### update_schema
Modifies the structure or definition of an existing JSON schema document.

## Prompt Examples

**Prompt:** 
```
Create a new private bin named 'AppConfig' with this JSON: {"theme": "dark", "version": 1.2}
```

**Response:** 
```
I've created the bin 'AppConfig'. The Bin ID is `65f1a...`. It is currently private and contains your configuration data.
```

**Prompt:** 
```
Read the data from bin ID 65f1a... but only return the 'theme' field using JSON Path.
```

**Response:** 
```
Fetching data with JSON Path filter... The value for 'theme' in that bin is: "dark".
```

**Prompt:** 
```
List all my existing collections on JSONBin.
```

**Response:** 
```
I found 3 collections: 'Production-DB', 'Staging-Configs', and 'User-Backups'. Which one would you like to inspect?
```

## Capabilities

### Create new data containers
You can create both collections (groupings) and individual JSON bins for structured storage.

### Read and filter records
Fetch the contents of a bin, optionally specifying a historical version or using JSON Path to pull out single fields.

### Manage data versions
Track every change made to your bins and count how many versions exist for auditing purposes.

### Structure and validate inputs
Define reusable JSON schemas and apply them to collections before adding new records.

### Handle large files
Create XL bins to store complex datasets up to 10MB that exceed standard limits.

### Control access and privacy
Manage which parts of the data are visible by creating or deleting restricted access keys, and setting bin privacy levels.

## Use Cases

### Testing API Mock Responses
You're building a feature that talks to an external service. Instead of writing those mock responses into temporary files, you use `create_bin` to store the JSON payload. Your agent then uses this MCP to ensure all subsequent logic runs against that controlled, persistent data source.

### Analyzing Multi-Step Research
Your agent gathers several pieces of information over a week. Instead of having 10 different chat threads, you use `list_collections` to create 'Project Alpha,' then use multiple calls to `create_bin` within it. You can later query the whole project using JSON Path and retrieve only the dates or names you need.

### Maintaining Agent State
You're running a long, multi-turn conversation that needs to remember user preferences (like dark mode setting: {"theme": "dark"}). You use `create_bin` to store this config and your agent uses the MCP to read it every time, ensuring consistency.

### Data Integrity Check
Before running a process that needs strict data rules, you first define them using `create_schema`, then attach that schema via `add_schema_to_collection`. This forces the system to validate any new bin created later.

## Benefits

- Stop losing data context. You can store complex API mock results using `create_bin` and retrieve them later via `read_bin`, keeping your entire workflow self-contained.
- Gain audit control with bin versioning. Instead of guessing what the data looked like last week, use `count_bin_versions` to track every change made to a record.
- Keep your project clean by grouping related assets. Use `create_collection` and then manage all associated bins using `fetch_collection_bins`, which is way better than dumping everything into one place.
- Need to process huge files? Don't use standard bins; use `create_xl_bin` for up to 10MB of data. This handles complex datasets that would otherwise crash your agent session.
- Refine your queries using JSON Path. When you read a bin, the `read_bin` tool lets your agent filter down to only one specific field, ignoring all the noise in the rest of the record.

## How It Works

The bottom line is: your AI client gains dedicated, persistent access to structured storage, letting it manage state outside of the chat window.

1. Subscribe to this MCP and provide your JSONBin.io Master Key and Access Key.
2. Your agent uses the tools to create a new collection or bin and populates it with structured JSON data.
3. The agent can then read that specific bin, querying fields using JSON Path or fetching an older version for review.

## Frequently Asked Questions

**How do I query specific fields using the JSONBin.io MCP?**
You use the `read_bin` tool and pass a JSON Path expression to filter your results. This lets you pull out only one field, like 'theme', without having to process the entire massive bin.

**What is the difference between `create_bin` and `create_xl_bin`?**
`create_bin` holds standard JSON data. Use `create_xl_bin` when your dataset is huge—up to 10MB—and needs specialized handling for complex, large-scale files.

**Can I rename a bin after creating it?**
Yep. You use the `update_bin_name` tool. This changes what the bin is called without touching any of the data inside it.

**How do I delete all history in a specific bin?**
If you want to wipe out every single version and piece of data from a bin, use `delete_all_bin_versions`. This clears everything while keeping the bin container itself.

**How do I secure data by creating a dedicated key using `create_access_key`?**
You generate a limited, scoped token that restricts exactly what the calling agent can do. This means your main master credentials aren't exposed when running workflows from external systems.

**Before I write to a group of bins, how do I validate the format using `add_schema_to_collection`?**
You apply a formal JSON schema document that dictates required fields and data types for the entire collection. This forces all incoming data into a predictable structure, preventing runtime errors.

**If I want to see all the JSON bins belonging to one project, what does `fetch_collection_bins` do?**
It retrieves a list of bin IDs and metadata associated with that specific collection name. This is much faster than listing every single individual bin across your entire account.

**How can I check which clients accessed my stored JSON data using `download_usage_logs`?**
You generate a log file detailing usage metrics, including timestamps and actions taken. This is useful for compliance reviews or debugging unexpected activity.

**Can I filter the data inside a bin without downloading the whole JSON?**
Yes. When using the `read_bin` tool, you can provide a `json_path` expression to filter the data on the server side and retrieve only the matching subset.

**How do I store datasets larger than the standard bin limit?**
You should use the `create_xl_bin` tool. This is specifically designed for large JSON files (up to 10MB) and requires a paid JSONBin.io plan with Early Access enabled.

**Is it possible to change a bin from public to private after creation?**
Absolutely. Use the `update_bin_privacy` tool with the target `bin_id` and set `is_private` to true or false as needed.