# GraphQL Fragment Merger MCP for AI Agents AI Agent Connect

> GraphQL Fragment Merger turns fragmented GraphQL queries into single, valid strings. It solves the problem of AI agents sending broken requests to endpoints that do not support fragment spreads by inlining everything into one complete operation.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_FF6uqVOpEFqWYmM3ysP7BLOCgkZbenjL7WWaqQoA/ai-agent-connect
- **Tags:** graphql, fragments, query-merger, api-compatibility, deterministic

## Description

If you have ever tried to have an AI agent interact with a GraphQL API, you know how quickly things break. You ask it to fetch some data, and it sends a query full of spread operators like ...UserFields. The problem is that many standard GraphQL endpoints do not actually understand those fragments; they expect a single, flat operation. This leads to constant errors and failed requests. This MCP fixes that by taking your fragmented queries and rewriting them into a single, complete string where every fragment is replaced by its actual fields. It handles the recursion for you, so even nested fragments get flattened properly. You can find this alongside thousands of other specialized tools in the Vinkius catalog. Instead of manually editing queries or writing custom scripts to clean up what your agent produces, you just let the MCP handle the heavy lifting. The result is a query that any standard GraphQL endpoint will accept without hesitation.

## Tools

### merge_graphql_fragments
Takes a query with fragments and inlines them into the main operation. This ensures your API requests are valid even if the endpoint lacks fragment support.

## Prompt Examples

**Prompt:** 
```
Can you merge this GraphQL query for me?
```

**Response:** 
```
I have processed your query. Here is the flattened version:

```graphql
query {
  user {
    id
    name
    email
  }
}
```
```

**Prompt:** 
```
Check if this fragment-heavy query will work on a standard endpoint.
```

**Response:** 
```
**Status:** Ready for execution.

I have inlined the fragments. The resulting operation is now a single, valid string:

| Field | Type |
| :--- | :--- |
| id | ID |
| name | String |
| email | String |
```

**Prompt:** 
```
Flatten this query: 'query { node { ...Node } } fragment Node on Node { id }'
```

**Response:** 
```
The fragments have been merged into a single operation:

```graphql
query {
  node {
    id
  }
}
```
```

## Capabilities

### Flatten nested fragments
Recursively replaces all fragment spreads with their actual field definitions.

### Fix broken API requests
Converts agent-generated queries into a format compatible with standard endpoints.

### Standardize query strings
Produces a single, deterministic string for every input query.

### Prepare queries for execution
Ensures your GraphQL operations are valid before they hit your server.

## Use Cases

### Fixing broken agent requests
An engineer asks Claude to fetch user data, but the generated query uses fragments that the server rejects. The MCP inlines them so the request succeeds.

### Automating API testing
A developer uses an agent to generate test payloads for a GraphQL API. This tool ensures every payload is syntactically valid for the target endpoint.

## Benefits

- Stop seeing 'Fragment not found' errors in your logs.
- Ensure compatibility with any standard GraphQL endpoint.
- Automate the cleanup of agent-generated queries.
- Handle deeply nested fragment structures without manual effort.
- Keep your AI agent's output clean and ready for execution.

## How It Works

The bottom line is you get a clean, flat query that works anywhere.

1. Input your raw GraphQL query containing fragment spreads and definitions.
2. The MCP identifies every spread operator and its corresponding definition.
3. You receive a single, valid GraphQL operation with all fields inlined.

## Frequently Asked Questions

**How does GraphQL Fragment Merger prevent API errors?**
It removes all fragment spreads and replaces them with the actual fields, so your server receives a complete query it can understand.

**Will GraphQL Fragment Merger work with nested fragments?**
Yes. The tool recursively follows every fragment definition until the entire query is flattened into a single layer of fields.

**Can I use GraphQL Fragment Merger with Claude or Cursor?**
Absolutely. Any MCP-compatible client can use this to clean up queries before they are sent to your GraphQL endpoint.

**Does GraphQL Fragment Merger change the actual data returned?**
No. It only changes the structure of the query string itself. The fields being requested remain exactly the same.

**Is GraphQL Fragment Merger useful for legacy APIs?**
It is specifically designed for this. If your older API does not support modern fragment syntax, this tool makes your agent's queries compatible.

**What does the `merge_graphql_fragments` tool actually do?**
It takes a GraphQL query string with fragments and returns a single, flattened query string where all fragment spreads have been replaced by their actual field definitions.

**Does it support nested fragments?**
Yes, the tool recursively processes fragment definitions to ensure all levels of nesting are resolved into the final query string.

**What happens if a fragment is not defined?**
The tool will return the `merged_query_string` as processed so far, along with an `unresolved_fragments` list containing the names of the missing fragments.