MCP server

VectorAmp exposes a Model Context Protocol (MCP) server for LLM clients and agents that support Streamable HTTP transport.

The MCP server lets an agent work with VectorAmp datasets end to end: discover organizations and datasets, create and manage datasets, insert vectors and add text, search, ask grounded questions, inspect and download retained source documents, upload files, and run schema-driven ingestion and scheduling workflows.

Production endpoint

The production MCP server is available at:

https://mcp.vectoramp.com/mcp

Client setup

VectorAmp MCP is a hosted remote MCP server. In modern MCP clients, setup is just the production URL:

https://mcp.vectoramp.com/mcp

You do not need an API key, local token, Node.js bridge, or manual OAuth configuration for interactive clients. Your MCP client discovers VectorAmp OAuth from the server, opens the browser sign-in flow, and stores the connection.

Cursor

Add VectorAmp to your Cursor MCP configuration:

{
  "mcpServers": {
    "vectoramp": {
      "url": "https://mcp.vectoramp.com/mcp"
    }
  }
}

After saving, Cursor should prompt you to authenticate with VectorAmp in the browser. Once connected, the VectorAmp tools are available in Cursor.

Claude Desktop

1. Click Customize.
2. Click Connectors.
3. Click Add, then choose Add Custom Connector.
4. Enter a name, such as VectorAmp.
5. Set the URL to https://mcp.vectoramp.com/mcp.
6. Click Add.
7. Click Connect if Claude does not connect automatically.

Claude should open the VectorAmp browser sign-in flow. Once connected, the VectorAmp tools are available in Claude.

Transport and authentication

VectorAmp MCP uses Streamable HTTP. Do not configure the legacy SSE transport. If your client asks for a transport explicitly, choose streamable-http.

The MCP server accepts two authentication methods:

Method	Best for	Organization
OAuth 2.0 / OIDC	Interactive clients where a person logs in via the browser	Selected from the user's memberships
API key (vsk_)	Headless agents, CI, scripted clients	Fixed by the key

OAuth-capable MCP clients handle browser login automatically by discovering VectorAmp's authorization server from the MCP endpoint. Unauthenticated requests to /mcp return 401 with WWW-Authenticate metadata for that discovery flow.

OAuth tokens include the organizations where the authenticated user is an active member. MCP uses that membership list to scope API calls to an organization. If the user belongs to exactly one organization, MCP selects it automatically. If the user belongs to multiple organizations, the client may need to call list_organizations and set_active_organization.

Other Streamable HTTP clients

If your MCP client supports remote Streamable HTTP directly, configure the server URL:

{
  "mcpServers": {
    "vectoramp": {
      "url": "https://mcp.vectoramp.com/mcp"
    }
  }
}

Some clients also accept an explicit transport value:

{
  "mcpServers": {
    "vectoramp": {
      "url": "https://mcp.vectoramp.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Advanced: API keys for headless clients

Use a VectorAmp API key only when you are configuring a headless agent, script, or CI job. Create one in the VectorAmp dashboard under Settings → API keys.

Send it on either header:

X-API-Key: vsk_...

Authorization: Bearer vsk_...

An API key is bound to a single organization, so there is no organization-selection step. Treat the key like a password: keep it in an environment variable or secret store, not in committed config.

For direct Streamable HTTP clients that support headers:

{
  "mcpServers": {
    "vectoramp": {
      "url": "https://mcp.vectoramp.com/mcp",
      "headers": {
        "X-API-Key": "vsk_..."
      }
    }
  }
}

Advanced: local stdio bridge

Most users should not need this. Use a bridge such as mcp-remote only for clients that cannot connect to remote Streamable HTTP MCP servers directly.

{
  "mcpServers": {
    "vectoramp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.vectoramp.com/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

When using mcp-remote, use Node.js 20.18.1+ or a current LTS release, keep the endpoint path as /mcp, and keep --transport http-only.

To pass an API key through mcp-remote, use a header and environment variable:

{
  "mcpServers": {
    "vectoramp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.vectoramp.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "X-API-Key:${VECTORAMP_API_KEY}"
      ],
      "env": {
        "VECTORAMP_API_KEY": "vsk_..."
      }
    }
  }
}

The no-space X-API-Key:${...} form avoids argument-escaping issues in some clients.

Advanced: temporary bearer tokens

Browser OAuth is preferred. If you are using a temporary OAuth bearer token for debugging, pass it to mcp-remote with a header:

export VECTORAMP_MCP_AUTH_HEADER="Bearer <VectorAmp access token>"
npx -y mcp-remote@latest https://mcp.vectoramp.com/mcp \
  --transport http-only \
  --header "Authorization:${VECTORAMP_MCP_AUTH_HEADER}"

The no-space Authorization:${...} form avoids argument-escaping issues in some clients.

Network access

mcp.vectoramp.com is the production MCP endpoint. Client-facing docs and examples should use the production URL.

Health and metrics

Health and metrics endpoints are separate from the MCP endpoint:

Endpoint	Purpose
GET /healthz	Liveness check
GET /readyz	Readiness check
GET /metrics	Prometheus metrics
/mcp	MCP Streamable HTTP endpoint

Tools

The server exposes MCP tools for organization selection, dataset lifecycle, vector/text writes, retrieval and RAG, document access, and schema-driven ingestion. Every tool returns a JSON object; defaults are shown after =. Tool names are parity-locked across the VectorAmp clients.

Organization selection

MCP scopes every data tool to one active VectorAmp organization.

Tool	Purpose
list_organizations()	List organizations where the authenticated user is currently an active member; returns the current selection and whether a selection is still required
set_active_organization(organization_id)	Select which organization subsequent MCP tool calls should use

If the authenticated user belongs to exactly one organization, MCP selects it automatically and does not ask the user to choose. If the user belongs to more than one organization and no active organization has been selected yet, organization-scoped tools ask the client to call list_organizations and then set_active_organization with one of the returned organization IDs.

list_organizations returns only active organization memberships carried by the OAuth/session token. It does not expose organizations where the user is not a member.

When you authenticate with an API key, organization selection does not apply: the key is bound to one organization, and the server uses that organization automatically. list_organizations / set_active_organization are only relevant for OAuth sessions that span multiple organizations.

Dataset tools

Tool	Purpose
list_datasets(limit=50, offset=0)	List datasets in the active organization; start here to find a dataset_id
get_dataset(dataset_id)	Fetch metadata for one dataset (dim, metric, index/hybrid settings, embedding config)
create_dataset(name, dim?, metric="cosine", embedding_provider="vectoramp", embedding_model?, hybrid=false, metadata?)	Create a SABLE dataset; only name is required. Defaults to VectorAmp-Embedding-4B (dim 2560). dim is auto-resolved from the embedding model; pass it explicitly for unknown models or embedding_provider="none". Set hybrid=true for dense+sparse.
delete_dataset(dataset_id)	Delete a dataset and all of its vectors/documents (irreversible)
get_dataset_stats(dataset_id)	Vector count, size, and index status; use to confirm an insert or job landed

A freshly created dataset's engine loads lazily, so it is usable right away — the first write may briefly retry while the engine warms up (the write tools handle this automatically).

Record (write) tools

Tool	Purpose
insert_vectors(dataset_id, vectors)	Insert pre-computed vectors. Each record is {id?, values: [float], metadata?, text?}; id may be a string or an integer (integers stay JSON numbers). values length must match the dataset's dim. Omit id to let the server assign one.
embed_text(dataset_id, text? | texts?, embedding_provider?, embedding_model?)	Generate embeddings with the dataset's model without inserting. Provide exactly one of text or texts.
add_texts(dataset_id, texts, ids?, metadatas?, embedding_provider?, embedding_model?)	Embed and insert in one call (the common way to add documents). Copies each text into metadata.text; ids/metadatas, when given, must match the length of texts; ids accept strings or integers.

Search and RAG tools

Tool	Purpose
search_dataset(dataset_id, text? | vector?, top_k=10, …)	Run semantic, vector, or hybrid search; returns raw matching records
ask_vectoramp(query, dataset_id?, top_k=5, conversation_history?, include_sources=true)	Ask a grounded question through VectorAmp Intelligence; returns a synthesized, cited answer

Use search_dataset when you want the raw matching records, and ask_vectoramp when you want a synthesized answer.

search_dataset parameters

Parameter	Required	Description
dataset_id	yes	The dataset to search.
text (alias search_text)	one of text/vector	Natural-language query; the server embeds it.
vector	one of text/vector	A pre-computed float vector. Provide exactly one of text or vector.
top_k	no	Number of results (default 10).
filters	no	Metadata equality filter (a dict).
advanced_filters	no	Structured advanced filter clauses.
hybrid, sparse_query, alpha	no	Hybrid search on hybrid datasets; alpha blends 0 = sparse … 1 = dense.
include_documents, include_metadata	no	Both default true.
include_embeddings	no	Default false.
rerank_enabled	no	Default false. When true, the only allowed values are rerank_provider="vectoramp" and rerank_model="VectorAmp-Rerank-v1".

ask_vectoramp parameters

ask_vectoramp returns a single non-streaming JSON answer with sources.

Parameter	Required	Description
query	yes	The question to answer.
dataset_id	no	Restrict retrieval to one dataset. Omit to search across all accessible datasets in the active organization.
top_k	no	Number of chunks to retrieve for grounding (default 5).
conversation_history	no	Prior turns as a list of {"role": "user" | "assistant", "content": "..."} objects, oldest first. Lets an agent ask multi-turn follow-ups; the agent decides how many prior turns to include.
include_sources	no	Whether to include source-level citations (default true).

Document tools

Tool	Purpose
list_dataset_documents(dataset_id, limit=50, cursor?, status?)	List retained source documents (cursor pagination); status ∈ processing|ready|failed|deleted
download_dataset_document(dataset_id, document_id)	Download a retained original; returns content_base64, content_type, content_disposition, byte_length

Content is base64-encoded so binary files round-trip safely. Dataset document IDs correspond to the same IDs returned by the REST dataset documents API.

Ingestion source and job tools

MCP ingestion tools are intentionally generic. Source type schemas and capabilities are owned by the Ingestion service, not hard-coded in MCP. New source types and options need no MCP code change.

Tool	Purpose
list_ingestion_source_types()	Discover available source types and capabilities from the registry
get_ingestion_source_schema(source_type)	Get the JSON config schema and capabilities for one source type
validate_ingestion_source(source_type, config)	Validate a proposed config before creating it
create_ingestion_source(source_type, name, config, description?, metadata?)	Register an ingestion source; returns its source_id
list_ingestion_sources(limit=50, offset=0)	List registered ingestion sources
get_ingestion_source(source_id)	Fetch one registered source (secrets redacted)
get_ingestion_source_references(source_id)	List what is using a source — active schedules + in-flight jobs (schedules, schedule_count, active_job_count, in_use)
delete_ingestion_source(source_id, force=false)	Delete a source; rejected with a conflict if it is in use unless force=true (which also disables its schedules)
list_unused_ingestion_sources()	List sources not attached to any active schedule or in-flight job (safe to delete)
cleanup_unused_ingestion_sources()	Delete all unused sources in one call; returns {deleted, count}
create_ingestion_job(source_id, dataset_id, pipeline_id?)	Start an ingestion job for a source and dataset
list_ingestion_jobs(dataset_id?, limit=50, offset=0)	List ingestion jobs, optionally filtered by dataset id
get_ingestion_job(job_id)	Fetch status and progress for one job
retry_ingestion_job(job_id)	Retry an eligible failed or cancelled job as a fresh full rerun (new job id)
cancel_ingestion_job(job_id)	Best-effort cancel of a pending/running job (see the note below)

The supported source types are web, s3, gcs, gdrive, jira, confluence, and file_upload. For a web crawl, config is {"start_urls": [...]}; for S3, {"bucket", "access_key_id", "secret_access_key"}; for Confluence, {"cloud_id" | "base_url", "username", "api_token", "spaces"}.

Operator configuration: source-type discovery and cancel

list_ingestion_source_types and get_ingestion_source_schema read the source-type registry, which has no public gateway route — it is served only by the ingestion service directly (/v1/source-types). They require the operator to set SOURCE_TYPES_BASE_URL to an ingestion-service base URL. When it is unset, those two tools return an actionable error naming the known source types (web, s3, gcs, gdrive, jira, confluence, file_upload), and you can still register any of them with create_ingestion_source without discovery.

cancel_ingestion_job likewise has no public gateway route. Treat cancel as best-effort: if it is rejected, let the job finish and ignore its output rather than relying on cancel.

The recommended ingestion flow is:

1. (Optional, if SOURCE_TYPES_BASE_URL is configured) call list_ingestion_source_types to discover supported source types, then get_ingestion_source_schema for the selected source_type and build a config matching the returned JSON schema. Otherwise build config directly for a known source type.
2. Optionally call validate_ingestion_source to catch schema or connector issues before creating anything.
3. Call create_ingestion_source with source_type, name, and config.
4. Call create_ingestion_job with the returned source_id and target dataset_id.
5. Track progress with list_ingestion_jobs or get_ingestion_job.
6. Use retry_ingestion_job if the job failed/cancelled and should be rerun.

Connection tools (authenticated sources)

Sources that read a private system (gdrive, gcs, confluence, jira) need credentials. For fully headless setups, pass a service account in the source config (e.g. service_account_json for gdrive/gcs) and skip connections entirely. For an interactive, reusable grant, create a connection — the user approves access in a browser once — and then create the source with connection_id in its config.

Tool	Purpose
list_connections(provider?)	List OAuth connections; optional provider filter (google or atlassian)
create_connection(provider, source_type?)	Start a grant; returns {id, provider, status: "pending", authorization_url}
get_connection(connection_id)	Fetch one connection; poll until status == "connected"
delete_connection(connection_id)	Revoke and delete a connection

A connection-backed authenticated flow is:

1. Call create_connection(provider="google", source_type="gdrive") and surface the returned authorization_url to the user to open in a browser.
2. Poll get_connection(connection_id) until status == "connected".
3. Call create_ingestion_source(source_type="gdrive", name=..., config={"folder_ids": [...], "connection_id": "<id>"}).
4. Call create_ingestion_job(source_id, dataset_id) and track it as usual.

Credentials are refreshed server-side at ingest time, so connection-backed sources keep working for scheduled jobs without re-consent.

File-upload tools

For loading local files directly (rather than pointing a connector at an existing store):

Tool	Purpose
upload_and_ingest(dataset_id, files)	Upload small files inline (base64) and ingest them in one call; files: [{filename, content_base64, content_type?}], capped by the inline limit (default 5 MB)
create_file_upload(dataset_id, files)	Begin a large-file upload and get presigned PUT URLs; files: [{filename, size_bytes?, content_type?}]
complete_file_upload(dataset_id, job_id, file_ids)	Finish an upload started with create_file_upload and start ingestion

For large files, use create_file_upload, PUT each file's bytes to its upload_url, then call complete_file_upload. For small files, upload_and_ingest runs the whole init → PUT → complete flow for you.

Ingestion schedule tools

Recurring ingestion schedules re-run a source into a dataset on a cron cadence.

Tool	Purpose
list_ingestion_schedules(limit=50, offset=0)	List recurring schedules
get_ingestion_schedule(schedule_id)	Fetch one schedule (cron, timezone, enabled, next_run_at)
create_ingestion_schedule(source_id, dataset_id, cron, timezone?, pipeline_id?, enabled?, name?, metadata?)	Create a recurring schedule
update_ingestion_schedule(schedule_id, cron?, timezone?, pipeline_id?, enabled?, name?, metadata?)	Update a schedule (at least one field required)
delete_ingestion_schedule(schedule_id)	Delete a schedule (does not delete the source or dataset)
trigger_ingestion_schedule(schedule_id)	Run a schedule now, outside its cron cadence

Resources

The server also exposes MCP resources:

Resource URI	Description
vectoramp://datasets	Dataset collection
vectoramp://datasets/{dataset_id}	Dataset details
vectoramp://datasets/{dataset_id}/documents	Retained source documents for a dataset
vectoramp://datasets/{dataset_id}/documents/{document_id}	One retained source document

Example workflows

Create a dataset and load text

No setup beyond an API key. Name-only create_dataset defaults to VectorAmp-Embedding-4B / dim 2560 / cosine / SABLE:

create_dataset(name="handbook")                       -> { id: "<id>", ... }
add_texts(dataset_id="<id>", texts=["...", "..."])     -> embeds + inserts
search_dataset(dataset_id="<id>", text="onboarding", top_k=5)

add_texts (and insert_vectors) retry automatically while a freshly created dataset's engine warms up, so they are safe to call immediately after create_dataset.

Retrieval and document analysis

A connected LLM client can:

1. call list_datasets to find available datasets,
2. call search_dataset to locate relevant chunks,
3. call ask_vectoramp for a grounded answer,
4. call list_dataset_documents to identify original source files,
5. call download_dataset_document to retrieve and analyze the original document.

This is especially useful for agents that need both semantic retrieval and access to the underlying retained source files.

Ingest an existing source

A connected LLM client can also create ingestion workflows. For a known source type you can register and start a job directly:

create_ingestion_source(source_type="web", name="Docs", config={"start_urls": ["https://docs.example.com"]})
create_ingestion_job(source_id="<src>", dataset_id="<id>")
get_ingestion_job(job_id="<job>")                     # poll until completed

When the operator has configured SOURCE_TYPES_BASE_URL, agents can stay forward-compatible by discovering schemas first — list_ingestion_source_types, then get_ingestion_source_schema(source_type) — and optionally validate_ingestion_source before creating. Because Ingestion owns the schema registry, this pattern keeps agents working as VectorAmp adds connectors, with no MCP-specific code changes.

Troubleshooting

• 404 or wrong transport: use the full URL https://mcp.vectoramp.com/mcp, not just the host. If your client asks for a transport, choose Streamable HTTP.
• Client asks for a local command: your client may not support remote Streamable HTTP directly. Use the mcp-remote bridge from the advanced section.
• OAuth does not open: remove and reconnect the VectorAmp MCP server in your client. The client should open a browser sign-in flow.
• Stale or broken OAuth state: disconnect VectorAmp in the MCP client and connect again. If you are using mcp-remote, clear the relevant local cache entries under ~/.mcp-auth and ~/.npm/_npx.
• 401 Unauthorized after login: disconnect and reconnect so the client runs the browser OAuth flow again.
• 401 Unauthorized with an API key: confirm the key is active and not expired (check Settings → API keys), and that it is passed as X-API-Key: vsk_... (or Authorization: Bearer vsk_...). A revoked or mistyped key returns 401.
• Multiple active organizations are available: call list_organizations, then set_active_organization with the organization you want to use.
• Source config validation failed: call get_ingestion_source_schema again and compare your config against the current Ingestion-owned JSON schema.
• Ingestion job cannot be retried: retry only applies to failed, cancelled, or all-files-failed jobs. Running or successful jobs are rejected.
• Ingestion job cannot be cancelled: the job may already be complete, failed, or in a state the ingestion API does not allow cancelling.
• Document unavailable: the dataset may not have retained originals, or the document may come from a source where VectorAmp cannot download/refetch the original.