Quickstart#

This guide walks through installing and running the OneTick MCP server from scratch. For the full environment variable reference see Configuration, and for production setup see Deployment.

Prerequisites#

  • Python 3.12

  • Docker — used in this guide to run a PostgreSQL + pgvector container for the search index. If you already have a PostgreSQL instance with the pgvector extension, you can skip the Docker step and use your existing connection string instead.

  • An OpenAI API key — used to generate embeddings when building the search index. For a no-egress alternative see Local embeddings.

  • OneTick Cloud WebAPI credentials (OTP_CLIENT_ID / OTP_CLIENT_SECRET) — required only for the symbology tool. You can skip these if you do not need search_symbol_universe.

Install#

Create a virtual environment and install the package:

python3.12 -m venv .venv
source .venv/bin/activate

pip install onetick-mcp

Download documentation sources#

Both the documentation search (collections) and reference data (csv) tool groups rely on OneTick documentation cloned locally. Create a document_sources directory and clone the required repositories into it:

mkdir document_sources
git clone https://github.com/onemarketdata/onetick-py-docs        document_sources/onetick-py-docs
git clone https://github.com/onemarketdata/onetick-sql-docs       document_sources/onetick-sql-docs
git clone https://github.com/onemarketdata/onetick-py-examples    document_sources/onetick-py-examples
git clone https://github.com/onemarketdata/onetick-cloud-coverage document_sources/onetick-cloud-coverage

Each of these is a clone of the current default branch — re-run the clones to pick up the latest published docs before rebuilding the index (see Deployment).

The two tool groups use this content differently:

  • The documentation search tools (collections) require an index build step before use — the documentation is embedded and stored in pgvector. This is covered in the Build the search index step below.

  • The reference data tools (csv) read the CSV files directly at request time — no build step is needed.

Start PostgreSQL with pgvector#

The search tools store their index in a PostgreSQL database with the pgvector extension. If you already have a PostgreSQL instance with pgvector available, skip this step and use your existing connection string in the Configure step below.

Otherwise, the quickest way to get started is with Docker:

mkdir -p onetick-pgdata

docker run -d \
  --name onetick-pgvector \
  -e POSTGRES_USER=onetick-user \
  -e POSTGRES_PASSWORD=onetick-password \
  -e POSTGRES_DB=onetick-db \
  -p 5432:5432 \
  -v "$(pwd)/onetick-pgdata:/var/lib/postgresql/data" \
  pgvector/pgvector:pg16

This container persists data to the ./onetick-pgdata directory so the index survives restarts.

Configure#

Create a .env file in the directory you will run the server from:

# pgvector connection — matches the Docker container started above
SQLALCHEMY_CONNECTION_STRING=postgresql+psycopg://onetick-user:onetick-password@localhost:5432/onetick-db

# OpenAI key for generating search embeddings
OPENAI_API_KEY=sk-...

# Path to the reference data CSV files
CSV_DATA_PATH=./document_sources/onetick-cloud-coverage

# OneTick Cloud credentials — required for the symbology tool
OTP_CLIENT_ID=
OTP_CLIENT_SECRET=

Note

If you do not have OneTick WebAPI credentials, you can skip the OTP_* variables and disable the symbology tool. See Enabling and disabling tool groups.

See Configuration for the full list of environment variables, including options for local embeddings, logging, and SSO.

Build the search index#

The search tools require a one-time index build. Run these two commands:

# Apply the database schema to the pgvector database
python -m onetick_llmbase.alembic --settings-module onetick_mcp.config upgrade head

# Embed and index all documentation sources
python -m onetick_llmbase.build_index -c onetick_mcp.config --source_path ./document_sources

The index build reads from ./document_sources, embeds each document, and stores the vectors in pgvector. Indexing time depends on the number of documents and the embedding model; with OpenAI embeddings expect a few minutes on a first run. To rebuild the index after updating documentation sources, see Deployment.

Run the server#

onetick-mcp

The server starts on port 8080 by default. To change the port or worker count see Configuration.

Verify it is running#

curl -f http://localhost:8080/health

A successful response confirms the server is up and all configured tools are loaded.