graphiti/RAILWAY_DEPLOYMENT.md

Railway Deployment Guide for Graphiti MCP Server

This guide helps you deploy the Graphiti MCP Server to Railway for use with ChatGPT and other MCP clients.

Prerequisites

• Railway account connected to GitHub
• OpenAI API key
• Neo4j database (local, Neo4j Aura, or Railway Neo4j service)

Railway Deployment Steps

1. Environment Variables

Set these environment variables in your Railway project:

Required:

• OPENAI_API_KEY: Your OpenAI API key (starts with sk-proj- or sk-)
• MODEL_NAME: gpt-4.1-mini (recommended)
• SMALL_MODEL_NAME: gpt-4.1-nano (recommended)

Database Configuration (choose one option):

Option A: Local Neo4j (for development/testing)

• NEO4J_URI: bolt://localhost:7687
• NEO4J_USER: neo4j
• NEO4J_PASSWORD: password

Option B: Neo4j Aura Cloud (recommended for production)

• NEO4J_URI: neo4j+s://your-instance.databases.neo4j.io
• NEO4J_USER: neo4j
• NEO4J_PASSWORD: Your Aura password

Option C: Railway Neo4j Service (if available)

• Use Railway's internal connection variables

Optional:

• LLM_TEMPERATURE: 0.0 (default)
• SEMAPHORE_LIMIT: 10 (concurrent operations limit)
• GRAPHITI_TELEMETRY_ENABLED: false (to disable telemetry)

2. Deploy to Railway

1. Connect Repository: Link your GitHub repository to Railway
2. Service Configuration: Railway will auto-detect the Dockerfile
3. Environment Variables: Set all required variables in Railway dashboard
4. Deploy: Railway will build and deploy automatically

3. Get Your Deployment URL

After successful deployment, Railway will provide a URL like: https://graphiti-production-xxxx.up.railway.app

Your MCP SSE endpoint will be: https://graphiti-production-xxxx.up.railway.app/sse

ChatGPT Integration

For ChatGPT with MCP Support

Configure your ChatGPT client with:

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "sse",
      "url": "https://your-railway-domain.up.railway.app/sse"
    }
  }
}

Custom ChatGPT Integration

If using a custom ChatGPT integration, make HTTP requests to:

• SSE Endpoint: https://your-railway-domain.up.railway.app/sse
• Tools Available: add_memory, search_memory_nodes, search_memory_facts, etc.

Claude Desktop Integration

For Claude Desktop (requires mcp-remote bridge):

{
  "mcpServers": {
    "graphiti-memory": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-railway-domain.up.railway.app/sse"
      ]
    }
  }
}

Testing Your Deployment

1. Verify Server Status

Visit: https://your-railway-domain.up.railway.app/sse

You should see an SSE connection established.

2. Test with MCP Inspector

npx @modelcontextprotocol/inspector --url https://your-railway-domain.up.railway.app/sse

Expected tools:

• add_memory
• search_memory_nodes
• search_memory_facts
• delete_entity_edge
• delete_episode
• get_entity_edge
• get_episodes
• clear_graph

3. Test Memory Operations

Add Memory:

{
  "name": "test_memory",
  "episode_body": "This is a test memory for verification",
  "source": "text"
}

Search Memory:

{
  "query": "test memory",
  "max_nodes": 5
}

Database Options

Neo4j Aura Cloud (Recommended)

1. Create a free Neo4j Aura instance at https://neo4j.com/aura/
2. Note the connection URI (starts with neo4j+s://)
3. Set environment variables in Railway:
   • NEO4J_URI: Your Aura connection string
   • NEO4J_USER: neo4j
   • NEO4J_PASSWORD: Your Aura password

Local Development Database

For testing with local Neo4j:

• Ensure your local Neo4j is accessible from Railway
• Consider using ngrok or similar for temporary access
• Not recommended for production

Security Considerations

1. API Keys: Never commit API keys to git. Use Railway environment variables.
2. Database Security: Use strong passwords and secure connection strings.
3. Access Control: Consider implementing authentication if needed.
4. HTTPS: Railway provides HTTPS by default.

Troubleshooting

Common Issues

Build Failures:

• Check Docker cache mount compatibility
• Ensure all dependencies are properly specified
• Review Railway build logs

Connection Issues:

• Verify environment variables are set correctly
• Check Neo4j database accessibility
• Ensure OpenAI API key is valid

Memory/Performance:

• Adjust SEMAPHORE_LIMIT for rate limiting
• Monitor Railway resource usage
• Consider Neo4j Aura for better performance

Debug Commands

Check server logs in Railway dashboard for:

• Connection status messages
• Environment variable loading
• Database connection status
• MCP server initialization

Support

For issues:

1. Check Railway deployment logs
2. Verify environment variables
3. Test database connectivity
4. Review MCP client configuration

For Graphiti-specific issues, see the main repository documentation.