Periscope MCP
OfficialUse Periscope MCP to discover and query data sources read-only, then inspect, page through, or download results.
List available data sources with their query languages, options, limits, and read-only layers.
Browse source metadata step by step, such as schemas, tables, columns, containers, prefixes, and key prefixes.
Start read-only queries across PostgreSQL, Oracle, SQL Server, Cosmos DB, Blob Storage, Log Analytics, Resource Graph, Redis, KIM, and declared REST APIs.
Get query status, progress, schema, row counts, window limits, and a manifest URL for downloading result files.
Read small windows of rows or referenced blob/KIM/REST text and images.
Cancel running queries; already-written result parts remain readable until expiry.
Provides strictly read-only query access to PostgreSQL databases, allowing agents to run a single SELECT statement and retrieve paged or downloadable results in Parquet format.
Provides strictly read-only query access to Redis standalone or cluster instances, allowing agents to run one read-only Redis command per query or use SCAN as a key export, with results returned as gzipped NDJSON.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Periscope MCP query appdata for 2026 claims and show the first 20 rows"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Periscope MCP
Periscope is an MCP server that gives AI agents strictly read-only query access to data sources:
Source | Query language | Result format |
PostgreSQL | SQL (one | Parquet |
Oracle Database (19c+) | SQL (one | Parquet |
SQL Server / Azure SQL | T-SQL (one | Parquet |
Azure Cosmos DB for NoSQL | Cosmos NoSQL query language | NDJSON (gzip) |
Azure Blob Storage | Glob or prefix, optional tag filter | NDJSON listing; contents referenced in place |
Azure Log Analytics / Application Insights | KQL | Parquet |
Azure Resource Graph (resources, Defender for Cloud, changes, role assignments) | KQL | NDJSON (gzip) |
Redis (standalone or cluster) | One read-only Redis command; | NDJSON (gzip) |
KIM | Node or record query language | NDJSON (gzip); offloaded contents referenced in place |
Any HTTP API ( | One HTTP request: request line, headers, body | NDJSON (gzip); binary responses referenced, fetched again on read |
Agents get the full read capability of each source. Writes cannot get through: on the API-based sources, write operations are never offered and are blocked on the wire; on the query-language sources they are filtered at several independent layers; for HTTP APIs, only the requests the operator declares as reads are sent. The guarantee holds even when the configured credential could write.
A query never returns data inline. It produces a result that the agent either pages through in small windows (read_result) or downloads over HTTP and processes with its own tools (curl, DuckDB, jq, pandas). The flow is the same for five rows or fifty million.
The full design is in docs/CONCEPT.md.
Tools
Tool | Purpose |
| Sources you may query, with query language, dialect hints, options and limits |
| Metadata, drilled down step by step (schemas → tables → columns, containers → sampled schemas, prefixes, …) |
| Starts a query and returns a |
| Status, schema, row counts, window limits and one manifest URL for downloads |
| One window of rows, or (blob, KIM and REST results) lines of a text file or an image |
| Stops a running query |
A typical session:
list_sources() → appdata (cosmos), erp (oracle), …
describe("appdata", "main/claims") → partition key, inferred schema
query("appdata", "SELECT * FROM c WHERE c.year = @y",
{ "@y": 2026 }, { "container": "claims" }) → r_7Hq2kV…
read_result("r_7Hq2kV…", limit: 20) → first rows (already while running)
get_result("r_7Hq2kV…", wait: 10) → succeeded, 1.8M rows, 19 files, 412 MBM="<download.manifestUrl>"; B="${M%/manifest.json}"
curl -fsS "$M" | jq -r '.files[].path' | xargs -P4 -I{} curl -fsS --create-dirs -o {} "$B/{}"
duckdb -c "SELECT status, count(*) FROM read_json('part-*.ndjson.gz') GROUP BY 1"Related MCP server: QuestLLens
Run locally (stdio)
Requires Node.js 24 and pnpm.
pnpm install
cp .env.example .env.periscope # add your sources
node src/index.ts --env-file .env.periscopeRegister it with Claude Code:
claude mcp add periscope -- node /path/to/periscope-mcp/src/index.ts --env-file /path/to/.env.periscopeIn stdio mode, results are stored in ./.periscope/results and download URLs point to a small HTTP endpoint on 127.0.0.1 that the server starts alongside.
With Docker (the published image runs the HTTP transport by default):
docker run -i --rm --env-file .env.periscope \
-e PERISCOPE_TRANSPORT=stdio -e PERISCOPE_HOST=0.0.0.0 -e PERISCOPE_PORT=8765 \
-e PERISCOPE_PUBLIC_URL=http://127.0.0.1:8765 -p 127.0.0.1:8765:8765 \
ghcr.io/coreprocess/periscope-mcp:0.1.0Deploy
Periscope is built to run as one container per project and environment, inside the network where the data sources are reachable, protected by Microsoft Entra ID (OAuth 2.1, MCP authorization spec): directly when the host is on a domain verified in the tenant, otherwise through Periscope's built-in authorization server, which signs users in at Entra (PERISCOPE_AUTH=entra-broker). See docs/deployment.md and the Terraform module in terraform/.
Configuration
Everything is configured through environment variables; sources are an indexed list:
PERISCOPE_SOURCE_N=2
PERISCOPE_SOURCE_0_NAME=shop
PERISCOPE_SOURCE_0_TYPE=postgres
PERISCOPE_SOURCE_0_URL=postgres://reader:secret@db:5432/shop
PERISCOPE_SOURCE_1_NAME=cache
PERISCOPE_SOURCE_1_TYPE=redis
PERISCOPE_SOURCE_1_URL=rediss://default:secret@cache:6380The full reference is in docs/configuration.md.
How read-only is enforced
Source | Layers |
Cosmos DB | Only read/query operations implemented; HTTP guard on the SDK lets only |
Blob Storage | Only list/read operations implemented; pipeline guard lets only |
Log Analytics | Query API only (it has no write operations); control commands rejected |
Resource Graph | Query API only (it has no write operations); its Resource Manager token is sent to that one endpoint only |
PostgreSQL |
|
Oracle |
|
SQL Server | Transaction that is always rolled back; strict T-SQL lexer (single |
Redis | Static allowlist of read-only, non-blocking commands; guard on every command the client writes to the socket; optional replica reads |
KIM | Service account key with only the Reader role; allowlist on every HTTP request (query, collection listing, type definitions, byte reads; no drafts, sessions, agents or exports); query check (no |
REST | Operator-declared allowlist of |
Each layer is tested on its own against real databases with write-capable credentials (see test/integration).
Development
pnpm lint # Biome
pnpm typecheck # TypeScript
pnpm test # unit tests
pnpm test:integration # needs Docker: Postgres, Oracle, SQL Server, Cosmos emulator, Azurite, Redis; KIM and REST run against mocks
pnpm buildLicense
MIT
Available Tools
6 toolscancel_queryCancel a running queryCRead-onlyIdempotent
Stops a running query. Parts already written stay readable until the result expires.
Inputs: resultId (required).
describeDescribe metadataARead-onlyIdempotent
Browses metadata of a source step by step (schemas/tables/columns, databases/containers with sampled schemas, blob prefixes, Log Analytics tables, Redis key prefixes). Use path to drill down and filter (with * wildcards) to narrow.
Inputs: source (required), path, filter.
get_resultGet result status and metadataBRead-onlyIdempotent
Status, progress, schema, row counts, window limits and download information (one manifest URL; all files are listed in the manifest). Use wait (seconds, max 10) to wait for a status change.
Inputs: resultId (required), wait.
list_sourcesList data sourcesARead-onlyIdempotent
Lists the data sources you may query: name, type, query language, dialect hints, options, limits and the active read-only layers.
Inputs: no named parameters.
queryStart a queryARead-only
Starts a read-only query and returns a resultId immediately. Query language depends on the source (see list_sources). Invalid or non-read-only queries are rejected right away with a reason. Then call get_result / read_result.
Inputs: query (required), source (required), params, options.
read_resultRead a window of a resultARead-onlyIdempotent
Returns one window of a result inline: rows (offset, limit, optional columns), or for blob results the content of a referenced text file by line range (file, lineOffset, lineLimit) or an image (file). Long values are truncated; downloads keep full values.
Inputs: resultId (required), file, limit, offset, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools split cleanly along the query lifecycle: discovery (list_sources, describe), execution (query, cancel_query), monitoring (get_result) and retrieval (read_result), and each description explains its role in the sequence. The only mild overlap is get_result vs read_result, which sound similar (status/manifest vs inline rows) and rely on the descriptions to separate.
Most names are consistent snake_case verb_noun (list_sources, get_result, read_result, cancel_query), which is predictable. The two bare verbs 'describe' and 'query' deviate slightly from the pattern but remain readable and verb-first.
Six tools is well-scoped for a read-only federated query service; each one maps to a distinct lifecycle stage (list, describe, start, poll, read, cancel) with no filler. Nothing feels thin or bloated.
The full async query lifecycle is covered: source discovery, metadata drill-down, query start, status/progress polling, windowed row/blob retrieval with download manifest, and cancellation. No obvious dead ends for a read-only query server.
Maintenance
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to securely query VAST Data databases for schema, metadata, and sample data via read-only SQL and MCP resources.MIT
- AlicenseNot gradedqualityCmaintenanceGives AI agents read-only access to any QuestDB instance, enabling schema discovery, time-series querying, and monitoring of partitions, WAL state, symbols, and ingestion health through MCP.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query a read-only data surface through typed tools, enforcing caller-specific row access, field masking, and withheld-row disclosure so they can retrieve entitled information without writes or silent data leakage.MIT
- AlicenseNot gradedqualityBmaintenanceGives AI agents read-only access to Postgres with parser-checked queries, hidden tables and columns, row limits and timeouts, caller-bound Row-Level Security, and a tamper-evident audit log.MIT