Skip to main content

Gemini SDK Integration

Use the Json2doc MCP server with Google's Gemini SDK to generate documents 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 JSON2DOC_API_KEY="your-json2doc-api-key"

Basic Usage​

from fastmcp import Client
from google import genai
import asyncio

# Create FastMCP client for Json2doc
mcp_client = Client(
    "https://mcp.json2doc.com/mcp",
    headers={"x-api-key": "your-json2doc-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 PDF document with a title 'Project Report' and a paragraph about our Q4 results.",
            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.json2doc.com/mcp",  # MCP server URL
    headers={
        "x-api-key": "your-json2doc-api-key"  # Your Json2doc 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 Json2doc API
async def fetch_schemas():
    async with httpx.AsyncClient() as client:
        headers = {"x-api-key": "your-json2doc-api-key"}
        
        # Fetch all three schemas
        document_schema = await client.get(
            "https://api.json2doc.com/api/v1/schemas/document",
            headers=headers
        )
        section_schema = await client.get(
            "https://api.json2doc.com/api/v1/schemas/section",
            headers=headers
        )
        template_schema = await client.get(
            "https://api.json2doc.com/api/v1/schemas/template",
            headers=headers
        )
        
        return {
            "document": document_schema.json(),
            "section": section_schema.json(),
            "template": template_schema.json()
        }

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

gemini_client = genai.Client()

async def main():
    # Fetch schemas first
    schemas = await fetch_schemas()
    
    # Invoice data
    invoice_data = {
        "customer": "Acme Corp",
        "amount": 2500.00,
        "items": [
            {"description": "Consulting Services", "amount": 2000.00},
            {"description": "Support Package", "amount": 500.00}
        ]
    }
    
    # Create prompt with schemas
    prompt = f"""
You have access to Json2doc tools for document generation.

IMPORTANT: Here are the JSON schemas you must follow:

Document Schema:
{schemas['document']}

Section Schema:
{schemas['section']}

Template Schema:
{schemas['template']}

Task: Create a professional invoice PDF for {invoice_data['customer']} 
with total amount ${invoice_data['amount']}.
Include these items: {invoice_data['items']}

Use the document builder approach:
1. Create a document builder session
2. Add sections for the invoice content
3. Generate the final PDF
"""
    
    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 Document 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.json2doc.com/mcp",
    headers={"x-api-key": "your-json2doc-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 PDF with a title 'Meeting Notes' and a paragraph summarizing our discussion.",
            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 Json2doc 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 Json2doc API

Connection Issues​

Solutions:

  • Verify the URL: https://mcp.json2doc.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