# 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.