Litmus logoLitmusEvals for humans.
On this page

Create a scoped API key and make your first MCP call in five minutes.

Quickstart

This walkthrough takes you from zero to a successful ping against the Litmus MCP server. It assumes Python 3.10+.

1. Create an API key

In your Litmus dashboard, open Settings → API Keys and click Create key. Name it after the client that will hold it, such as local dev or ci runner.

Choose its permissions. Nothing is ticked to start with. ping needs none, so tick what you plan to call next: roles:read and submissions:read let an agent list roles and read results, and Full access grants everything. The tool reference lists the permission each tool needs, and a tool the key lacks one for returns an error naming it.

Copy the key when it appears. Litmus shows it once. A key belongs to your org, not to a person, so treat it like any production credential and revoke it if it leaks. You can change its permissions later without replacing it; see Authentication & scopes.

2. Install the MCP Python SDK

bash
pip install mcp

3. Connect and call ping

Copy your org's MCP URL from Settings → API Keys, set the bearer header to your key, and open a streamable HTTP session:

python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": "Bearer litmus_sk_..."}  # paste your key
    async with streamablehttp_client(
        "https://litmushiring.com/mcp/<your-org-id>/", headers=headers
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("ping", {"message": "hello"})
            print(result.content[0].text)

asyncio.run(main())

If everything is wired up, the program prints pong: hello and exits.

4. Next steps

  • For ChatGPT, Claude, Cursor and other interactive clients, connect with OAuth instead: point the client at the URL and it handles sign-in. See Authentication → OAuth.
  • Browse the tool reference to see what you can call.
  • Hit a snag? Troubleshooting covers the common failure modes.
    Quickstart · Litmus docs