Skip to main content

Gemini SDK Integration

Use the JsonCut MCP server with Google's Gemini SDK to generate images and videos programmatically.

Gemini MCP Limitations

Gemini's MCP support currently only accesses tools from MCP servers—it does not support resources. This means the JSON schemas are not automatically available to the AI. You have two options:

  1. Fetch schemas manually (recommended) - Download schemas from the endpoints and provide them in your prompt
  2. Let the AI work without schemas - The AI will attempt to construct valid configurations but may make errors

See Example 1 below for how to fetch and use schemas.

Prerequisites​

Installation​

pip install google-genai fastmcp httpx

Set your API keys as environment variables:

export GEMINI_API_KEY="your-gemini-api-key"
export JSONCUT_API_KEY="your-jsoncut-api-key"

Basic Usage​

from fastmcp import Client
from google import genai
import asyncio

# Create FastMCP client for JsonCut
mcp_client = Client(
    "https://mcp.jsoncut.com/mcp",
    headers={"x-api-key": "your-jsoncut-api-key"}
)

gemini_client = genai.Client()

async def main():
    async with mcp_client:
        response = await gemini_client.aio.models.generate_content(
            model="gemini-2.0-flash",
            contents="Create a social media image with the text 'New Product Launch' on a gradient background.",
            config=genai.types.GenerateContentConfig(
                temperature=0,
                tools=[mcp_client.session],  # Pass the FastMCP client session
            ),
        )
        print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

Configuration Options​

FastMCP Client Configuration​

from fastmcp import Client

mcp_client = Client(
    "https://mcp.jsoncut.com/mcp",  # MCP server URL
    headers={
        "x-api-key": "your-jsoncut-api-key"  # Your JsonCut API key
    }
)

Gemini Configuration​

config = genai.types.GenerateContentConfig(
    temperature=0,              # Control randomness (0 = deterministic)
    tools=[mcp_client.session], # Pass the FastMCP client session
)

Examples​

Since Gemini doesn't support MCP resources, fetch the schemas manually and include them in your prompt:

from fastmcp import Client
from google import genai
import asyncio
import httpx

# Fetch schemas from JsonCut API
async def fetch_schemas():
    async with httpx.AsyncClient() as client:
        headers = {"x-api-key": "your-jsoncut-api-key"}
        
        # Fetch image and video schemas
        image_schema = await client.get(
            "https://api.jsoncut.com/api/v1/schemas/image",
            headers=headers
        )
        video_schema = await client.get(
            "https://api.jsoncut.com/api/v1/schemas/video",
            headers=headers
        )
        
        return {
            "image": image_schema.json(),
            "video": video_schema.json()
        }

# Create MCP client
mcp_client = Client(
    "https://mcp.jsoncut.com/mcp",
    headers={"x-api-key": "your-jsoncut-api-key"}
)

gemini_client = genai.Client()

async def main():
    # Fetch schemas first
    schemas = await fetch_schemas()
    
    # Image data
    image_data = {
        "title": "Summer Sale",
        "discount": "50% OFF",
        "background": "gradient"
    }
    
    # Create prompt with schemas
    prompt = f"""
You have access to JsonCut tools for media generation.

IMPORTANT: Here are the JSON schemas you must follow:

Image Schema:
{schemas['image']}

Video Schema:
{schemas['video']}

Task: Create a promotional image with title '{image_data['title']}' 
and discount text '{image_data['discount']}' 
on a {image_data['background']} background.

Use the image generation approach:
1. Create an image job with the appropriate configuration
2. Add layers for background, text, and effects
3. Generate the final image
"""
    
    async with mcp_client:
        response = await gemini_client.aio.models.generate_content(
            model="gemini-2.0-flash",
            contents=prompt,
            config=genai.types.GenerateContentConfig(
                temperature=0,
                tools=[mcp_client.session],
            ),
        )
        print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

Example 2: Simple Image Generation​

For simpler use cases, you can let Gemini work without schemas (though this may be less reliable):

from fastmcp import Client
from google import genai
import asyncio

mcp_client = Client(
    "https://mcp.jsoncut.com/mcp",
    headers={"x-api-key": "your-jsoncut-api-key"}
)

gemini_client = genai.Client()

async def main():
    async with mcp_client:
        response = await gemini_client.aio.models.generate_content(
            model="gemini-2.0-flash",
            contents="Create a simple image with the text 'Meeting Notes' on a blue background.",
            config=genai.types.GenerateContentConfig(
                temperature=0,
                tools=[mcp_client.session],
            ),
        )
        print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

Troubleshooting​

Authentication Errors​

Solutions:

  • Verify your JsonCut API key in the dashboard
  • Check the header name is x-api-key
  • Ensure no extra spaces in the key
  • Verify the key hasn't expired
  • Set GEMINI_API_KEY environment variable

Schema Validation Errors​

Solutions:

  • Always fetch and provide schemas in your prompt (see Example 1)
  • Verify the schemas are correctly formatted in the prompt
  • Check that the AI is following the schema structure
  • Review error messages from the JsonCut API

Connection Issues​

Solutions:

  • Verify the URL: https://mcp.jsoncut.com/mcp
  • Check your internet connection
  • Ensure firewall allows the connection
  • Verify both API keys are set correctly

MCP Client Context Errors​

Solutions:

  • Always use async with mcp_client: to enter the client context
  • Ensure you're using asyncio.run() to run async code
  • Check that the FastMCP client is properly initialized