Skip to main content
This guide walks you through setting up a repository to sync with Osmosis AI platform.

Prerequisites

  • GitHub account
  • Python 3.10 or higher
  • Git installed locally
  • Osmosis AI account

Step 1: Create Repository Structure

Create the required directory structure:
Your structure should look like:

Step 2: Add Python Dependencies

Create pyproject.toml in the repository root:

Step 3: Set Up MCP Server

Create Server Configuration

File: mcp/server/__init__.py
File: mcp/server/mcp_server.py

Create Entry Point

File: mcp/main.py

Add Your First Tool

File: mcp/tools/__init__.py
File: mcp/tools/math.py

Step 4: Add Reward Function

File: reward_fn/compute_reward.py

Step 5: Add Reward Rubric

File: reward_rubric/reward_rubric_openai.py

Step 6: Test Locally

Install Dependencies

Test MCP Server

Start the server:
In another terminal, test the server:

Test Reward Function

Expected output: 1.0

Test Reward Rubric

Set your API key:
Test the rubric:

Step 7: Create .gitignore

Create .gitignore to exclude sensitive and generated files:

Step 8: Push to GitHub

Initialize git and push:

Step 9: Connect to Osmosis Platform

You can connect both public and private repositories to Osmosis. For private repositories, you’ll need to grant Osmosis access through GitHub OAuth or a deploy key.
  1. Navigate to your Osmosis workspace settings at platform.osmosis.ai/settings/workspace/git
  2. Click Connect Repository
  3. Authorize Osmosis to access your GitHub account
  4. Select your repository from the list
  5. For private repos: Grant necessary permissions when prompted
  6. Click Connect and wait for initial sync

Step 10: Verify Sync

After connecting, Osmosis will automatically sync your repository. Verify the sync:
  1. Check the Git Sync dashboard to see sync status
  2. Navigate to MCP Tools to see your tools listed
  3. Go to Reward Functions to verify your reward functions
  4. Check Reward Rubrics for your rubric implementations
Sync typically completes within 2-3 minutes.

Next Steps

Add More Components

Now that you’re set up, you can add more functionality:

Add More Tools

Create additional MCP tools

More Reward Functions

Build custom scoring logic

Set Up CI/CD

Create .github/workflows/test.yml:

Configure Environment Variables

For local development, create .env file:
For Osmosis platform:
  1. Go to Settings → Environment Variables
  2. Add your API keys securely
  3. Reference them in your rubric functions

Troubleshooting

Sync Not Working

  • Verify folder structure matches exactly
  • Check that decorators are used correctly (@mcp.tool(), @osmosis_reward, @osmosis_rubric)
  • Ensure pyproject.toml includes all required dependencies
  • Review GitHub webhook settings in repository settings

Tools Not Appearing

  • Confirm @mcp.tool() decorator is present
  • Check that tools are exported in mcp/tools/__init__.py
  • Verify type hints are included for all parameters
  • Review Osmosis sync logs for errors

API Key Issues

  • For local testing, set environment variables properly
  • For Osmosis platform, configure secrets in dashboard settings
  • Never commit API keys to version control (use .gitignore)
  • Verify API keys are valid and have proper permissions

Import Errors

  • Ensure __init__.py files exist in all package directories
  • Check that imports use correct relative paths
  • Verify all dependencies are installed: pip install -e .

Complete Example

For a complete working example, check out:

Example Repository

Explore the official Osmosis Git Sync example with all components implemented

Getting Help

Need assistance? Here are your resources: