grounding 0.2.0

CLI tooling for the Grounding MCP server

Grounding CLI

grounding is a Python-based command-line tool that helps developers authenticate with the Grounding platform, mint per-agent MCP tokens, and wire those tokens into Model Context Protocol (MCP) agents. It also bundles a local copy of the Grounding MCP server for testing.

Installation

pip install grounding

Tip: pipx install grounding keeps the CLI isolated from your system Python.

First-time setup

1. Supabase connection info ships with the CLI via environment variables (GROUNDING_SUPABASE_URL, GROUNDING_SUPABASE_ANON_KEY). If you need to override them, run grounding config supabase with your project values.

2. Log in with your Grounding developer account using an OAuth PKCE flow. The CLI opens a browser window; if that fails it prints the URL so you can copy/paste manually.

   grounding auth login
   

3. Verify the session:

   grounding auth status
   

Managing MCP agent tokens

Create a token for each automation agent you operate. The CLI stores the full token locally (chmod 600) so you can reuse it later.

For GUI Tools (Claude Desktop, Cline, VS Code)

These configurations work with GUI-based AI assistants that support MCP:

grounding agent create my-agent
# → prints fg_xxxxx.yyyyy and stores it locally

# Import a token minted from the dashboard
grounding agent import my-agent fg_abcdef12.verysecrettoken

# List local and remote tokens
grounding agent list --remote

# Remove a stored token
grounding agent forget my-agent

# Revoke or rotate a token directly from the CLI
grounding agent revoke my-agent
grounding agent rotate my-agent

Generate a ready-to-paste MCP client configuration snippet for your agent:

grounding agent config my-agent --format claude-desktop

Formats:

• claude-desktop – Configuration for Claude Desktop (macOS/Windows)
• cline – Configuration for Cline VS Code extension
• vscode – Configuration for VS Code native MCP support
• generic – Generic MCP client configuration for any compatible client

Example configurations

Claude Desktop (default format):

grounding agent config my-agent --format claude-desktop

Output includes the config file path and JSON to add to claude_desktop_config.json:

{
  "mcpServers": {
    "grounding": {
      "type": "http",
      "url": "https://api.grounding.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Cline (VS Code extension):

grounding agent config my-agent --format cline

Output includes instructions to configure via Cline's MCP Servers UI.

VS Code (native MCP):

grounding agent config my-agent --format vscode

Output can be added to .vscode/mcp.json (workspace) or global user configuration.

For SDK Integration (OpenAI, Anthropic, Google)

All major LLM providers now have native MCP support! You can integrate with minimal or zero code:

OpenAI - Native MCP (Zero Code!)

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="o4-mini-deep-research",
    input=[{"role": "user", "content": [{"type": "input_text", "text": "Find Gmail compose"}]}],
    tools=[{
        "type": "mcp",
        "server_label": "grounding",
        "server_url": "https://api.grounding.dev/mcp/sse/",
        "allowed_tools": ["list_surfaces", "get_feature", "find_feature", "list_keyboard_shortcuts"],
        "require_approval": "never"
    }]
)

Anthropic - Native MCP (Zero Code!)

from anthropic import Anthropic

client = Anthropic()
response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Find Gmail compose"}],
    mcp_servers=[{
        "type": "url",
        "url": "https://api.grounding.dev/mcp",
        "name": "grounding",
        "authorization_token": "fg_xxxxx.yyyyy"
    }],
    extra_headers={"anthropic-beta": "mcp-client-2025-04-04"}
)

Google Gemini - Native MCP (Minimal Code!)

from google import genai
from google.genai import types
from mcp import ClientSession
from mcp.client.http import http_client

client = genai.Client()
async with http_client(url="https://api.grounding.dev/mcp", headers={"Authorization": "Bearer fg_xxxxx.yyyyy"}) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        response = await client.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="Find Gmail compose",
            config=types.GenerateContentConfig(tools=[session])
        )

Need manual control? Install our helper library:

pip install 'grounding[openai]'    # For OpenAI manual control
pip install 'grounding[anthropic]' # For Anthropic manual control
pip install 'grounding[google]'    # For Google Gemini manual control

See SDK Integration Guide for complete examples, multi-turn conversations, and when to use native vs. helper library approaches.

Supabase prerequisites

The CLI uses two Postgres functions (exposed as Supabase RPC endpoints) to mint and revoke MCP tokens:

• issue_mcp_agent_token(agent_name text) – returns a JSON payload containing token, token_id, token_prefix, and metadata.
• revoke_mcp_agent_token(token_id uuid) – marks an existing token as inactive.

Ensure these functions run with security definer privileges and enforce that auth.uid() matches the token developer_id.

Environment variables

The CLI respects the following overrides:

Variable	Purpose
GROUNDING_SUPABASE_URL	Default Supabase project URL.
GROUNDING_SUPABASE_ANON_KEY	Public anon key.
GROUNDING_SUPABASE_CLIENT_ID	Optional Supabase client ID for PKCE refresh.
GROUNDING_SUPABASE_PROVIDER	Default OAuth provider (e.g. github, google).
GROUNDING_OAUTH_SCOPES	Space-delimited scope list for the auth flow.
GROUNDING_REDIRECT_PORT	Local port for the PKCE callback server.
GROUNDING_MCP_URL	Hosted MCP endpoint for snippet generation.

When publishing the CLI to PyPI, remember to include the Node assets via python -m build and verify the resulting wheel contains grounding/server/node/* files.

Running the bundled MCP server (optional)

The primary deployment model is to call the hosted MCP endpoint with your issued tokens. For smoke testing or air-gapped environments you can launch the bundled Node server:

grounding server start --agent my-agent

On first run this command installs Node dependencies into a cache directory under ~/.cache/grounding/server. Provide --token to pass a raw token string instead of referencing a stored agent.