Skip to main content

PhenoWorks MCP

Connect your AI assistant to PhenoWorks with the Model Context Protocol (MCP). The assistant can find projects and datasets, inspect analysis modules, run pipelines, and retrieve results using your PhenoWorks account permissions.

This package runs the MCP server that your assistant connects to. You need a running PhenoWorks server and an MCP-compatible assistant; installing this package does not install PhenoWorks or provide an AI model.

Before you start

  • Use Python 3.11 or newer.
  • Have your PhenoWorks server URL, such as https://your-phenoworks-server.
  • Create an API key in your PhenoWorks account settings.

Your server URL is the address of your own PhenoWorks installation, not the public documentation website. Both the server root and a URL ending in /api are accepted.

Install

Install from PyPI in a Python virtual environment:

pip install phenoworks-mcp
phenoworks-mcp --help

The PhenoWorks Python SDK and MCP runtime are installed automatically. To upgrade an existing installation, run pip install --upgrade phenoworks-mcp.

If you already use uv, you can run the package without a separate install command:

uvx phenoworks-mcp --help

Connect to Claude Desktop

Follow the Claude Desktop setup tutorial to create a dedicated uv environment, configure your local PhenoWorks connection, and start chatting with Claude.

Connect over local HTTP

For a client that accepts a Streamable HTTP MCP URL, start the server in a terminal. For example, in a macOS or Linux shell:

export PHENOWORKS_API_BASE_URL="https://your-phenoworks-server"
export PHENOWORKS_PUBLIC_URL="https://your-phenoworks-app"
export PHENOWORKS_API_KEY="YOUR_API_KEY"
phenoworks-mcp

Leave the process running and add this MCP server URL to your assistant:

http://127.0.0.1:8787/mcp

There are three relevant URLs: PHENOWORKS_API_BASE_URL points to the PhenoWorks API, PHENOWORKS_PUBLIC_URL points to the browser application, and http://127.0.0.1:8787/mcp points to this MCP process. The default listens only on your computer, so a cloud-hosted assistant cannot reach it through its own localhost.

You can change the local port if needed:

phenoworks-mcp --port 8788

When configured with a fixed API key, callers of this MCP process act as that PhenoWorks account. Keep this mode local to a trusted user.

Try your first requests

Once connected, ask your assistant:

  • "Check my PhenoWorks connection and show which account I am using."
  • "List my projects, then show the datasets in the project I choose."
  • "Find datasets configured for thermal imagery in project 7."
  • "Show the available analysis modules and explain the inputs of one I choose."
  • "List my knowledge bases, then use the Remote Sensing collection to answer my questions with citations."
  • "Check the status of pipeline 123 and list its output artifacts."

Replace example IDs with IDs from your server. A useful first sequence is phenoworks_health, phenoworks_me, then list_projects. A successful health check establishes connectivity; phenoworks_me checks the account credentials.

For analysis, ask the assistant to discover the installed blocks and validate the steps before using run_dataset_pipeline. Pipeline execution needs suitable dataset inputs and a working PhenoWorks worker. Running or cancelling a pipeline changes server state. Clients that support form elicitation receive a submission confirmation; clients without it can submit directly, so use your assistant's tool approval controls as appropriate.

Available tools

Task Tools
Check connectivity and identity phenoworks_health, phenoworks_me
Explore projects list_projects, get_project
Environmental data get_dataset_ancillary_data
Explore datasets list_datasets, get_dataset, get_dataset_summary, filter_datasets_by_modality
Use indexed research documents list_knowledge_bases, search_knowledge_bases
Understand data types list_data_types
Prepare and upload data get_data_import_guide
Inspect analysis modules search_analysis_blocks, describe_analysis_block, review_analysis_block_code
Retrieve module citations get_analysis_block_citation
Prepare and run analysis validate_pipeline_steps, run_dataset_pipeline
Monitor runs list_pipeline_runs, get_pipeline_run, cancel_pipeline_run
Retrieve results list_artifacts, download_artifact

Every tool result is sent back to the model on each turn, so large outputs are kept small: list_pipeline_runs and list_artifacts return one page (limit/offset, newest first) with a total and next_offset, run summaries omit logs and payloads, and get_pipeline_run returns only the last log_lines lines of the logs (200 by default). Instead of listing a run's files, get_pipeline_run adds an artifacts overview: a count per artifact type and the run's results table, so an agent can offer that one file when a user asks for "the results" of a run with thousands of per-plot outputs. list_artifacts accepts an artifact_type filter for fetching one kind of file.

Available data and actions depend on the account's server permissions. Modality filtering checks the dataset's declared modalities, not whether its files have already been uploaded.

Knowledge-base selection is explicit and stateless. Call list_knowledge_bases to resolve a collection name to its ID, ask the user to choose one or more collections, and pass those IDs to every relevant search_knowledge_bases call. The MCP server never searches every collection by default. Set PHENOWORKS_PUBLIC_URL to the browser-facing application URL so returned citations open the source document in the PhenoWorks editor.

Where downloaded files go

download_artifact saves files on the computer running this MCP server. That is right when the server runs on your own computer, as with Claude Desktop or Claude Code over stdio. A shared server started with --no-local-downloads saves nothing: the tool checks access and returns the artifact ID, filename, and size without local_path, and the caller's client offers the download. The PhenoWorks web app runs its MCP service this way and shows a download button in the agent chat. By default, the workspace is .phenoworks-agent-workspaces under the process's working directory. To choose a location, set an absolute path:

export PHENOWORKS_AGENT_WORKSPACE_DIR="/absolute/path/to/phenoworks-downloads"

For a desktop client, add this variable to its MCP configuration's env object. With an API key or token, the server acts for one user, so files are saved directly in the workspace as artifact_<id>_<filename>. With --forward-auth-headers, the server is shared, so each file goes under user_<id>/<session>/ inside the workspace. The user folder comes from the authenticated identity, and the session folder comes from the x-phenoworks-agent-session header (default when it is missing). An assistant running on another computer will need shared storage or another way to retrieve those local files.

Other authentication options

Use exactly one credential mode:

Mode Configuration
API key PHENOWORKS_API_KEY
Bearer token PHENOWORKS_AUTH_TOKEN instead of the API key
Each caller supplies credentials --forward-auth-headers over HTTP

For forwarded authentication, unset fixed credentials before starting:

unset PHENOWORKS_API_KEY PHENOWORKS_AUTH_TOKEN
phenoworks-mcp \
  --api-base-url https://your-phenoworks-server \
  --forward-auth-headers

Each MCP caller must send either X-API-Key or Authorization: Bearer .... This mode is not available with stdio. Remote deployments also need a reachable address, HTTPS, and appropriate access controls; changing --host alone does not configure those services.

Troubleshooting

What you see What to check
phenoworks-mcp: command not found Activate the environment where you installed it, or give your client the executable's full path.
Missing API endpoint Set PHENOWORKS_API_BASE_URL or pass --api-base-url. The MCP CLI uses this variable, not the SDK's PHENOWORKS_API_URL.
Citation opens the wrong application Set PHENOWORKS_PUBLIC_URL to the browser-facing PhenoWorks URL, then restart the MCP client.
Missing or conflicting credentials Set exactly one authentication mode. Remove an old bearer token when switching to an API key.
Connection refused Check that PhenoWorks is running and that the MCP host can reach its URL. For HTTP clients, also keep the MCP process running.
HTTP 401 or 403 Check the key/token, its expiry where applicable, and the account's access permissions.
Tools do not appear after a change Restart the MCP connection or client to refresh tool discovery.
Downloads are not on your laptop Check the MCP host's workspace directory; files are saved where the server runs. A server started with --no-local-downloads saves none.
Cannot create the download folder Set PHENOWORKS_AGENT_WORKSPACE_DIR to an absolute folder the MCP process can write to (no placeholders such as YOUR_USERNAME), then restart the server.

See the PhenoWorks documentation for setting up projects, data, and workflows.

Implementation and lifecycle

The Python SDK owns the pooled asynchronous HTTP client, credential validation, and API error decoding. Inside phenoworks_mcp:

Module Responsibility
cli.py Resolves arguments and environment configuration, then starts the server.
server.py Builds the server, owns the client lifespan, and registers each tool group.
tools/ One module per tool group, including catalog, files, knowledge, blocks, pipelines, and artifacts.
api.py PhenoWorksGateway: per-request credentials, API errors as tool errors, per-caller workspace folders on shared servers.
responses.py Pure functions that shape API records into compact results (summaries, pages, log tails).
blocks.py Block API paths, read-only source excerpts, and pipeline step resolution.
workspace.py Safe download locations inside the agent workspace.
settings.py Every limit, default, and environment setting.
instructions.py Server instructions describing the data model and analysis workflow.

Numeric tool parameters declare their bounds in the tool schema, so clients see them and out-of-range values are rejected before a tool runs. Source docstrings describe parameters, return contracts, validation, and resource ownership.

build_server(client) transfers client cleanup to the MCP server lifespan. Embedders invoking tools directly outside that lifespan must close the client themselves. Forwarded credentials are supplied per request and never written into shared client defaults. The backend remains the authority for access checks.

get_dataset_summary first fetches the dataset, then concurrently fetches its surveys, all file pages, ancillary data, layers, pipeline runs, and artifacts. It returns the keys dataset, surveys, contents, ancillary_data, layers, pipeline_runs, and artifacts, and fails if a required request fails. contents summarizes, for the dataset and for each survey, the data products present with their sensors (modalities), named bands, processing methods, and plot coverage, so an agent can match analysis blocks to the data.

run_dataset_pipeline accepts optional modalities and data_products filters that narrow which files reach the blocks. The server also publishes agent instructions describing this vocabulary and the analysis planning workflow. This reduces sequential network waits; it is not a measured production latency guarantee.

Explicit pipeline step versions are preserved; otherwise the account's preferred version is resolved from the catalog. Canonical names take precedence over class/display aliases, and argument values must be objects. validate_pipeline_steps checks compatibility without submitting work. Pipeline submission returns a single run_id, which is also the run's operation id. Clients without form elicitation retain headless submission behavior. Once a client advertises support, a failed confirmation stops submission; it never silently authorizes the run.

Downloads stream in 1 MiB chunks to unique temporary files and atomically replace the final artifact path. The last successful download wins for the same artifact path; no caller consumes another download's partial file. Temporary files are removed on normal errors and cancellation. A download that cannot create its folder or write its file fails with a tool error naming the path. With forwarded credentials, paths are scoped by the API-authenticated user and a sanitized x-phenoworks-agent-session grouping header. That header is not an authorization credential. SHA-256 and byte counts describe the downloaded bytes. The workspace is local to the MCP host, so remote agent hosts need shared storage or a separate retrieval mechanism.

Offline checks

The server uses MCP 2.x (mcp.server.mcpserver). From the repository root, install the local package and run these standard-library tests without pytest:

pip install -e ./packages/phenoworks-mcp
python -m unittest discover -s packages/phenoworks-mcp/tests -v

Tests cover concurrent summaries, canonical catalog resolution, invalid step arguments, concurrent downloads, and confirmation failures. They use fake API clients and temporary directories; they do not submit real pipelines.

Describe and explain analysis blocks

Use search_analysis_blocks to find the canonical block name, then:

  • describe_analysis_block(name, version=None) returns its description, schema, manifest, class name, authors, tags, and installed version. This is catalog metadata, not an inferred explanation of the implementation.
  • review_analysis_block_code(name, version=None, start_line=1, max_lines=200) returns version-matched metadata and the stored block.py source, with line numbers and a full-source SHA-256 digest. The agent can explain processing steps, inputs, outputs, and side effects using this evidence. No code is imported or executed, and the tool does not generate an automated correctness verdict.

For example, after finding image_2_hsv, call:

{"name": "image_2_hsv", "start_line": 1, "max_lines": 200}

Continue with next_start_line and the returned version to inspect subsequent pages; next_start_line: null means the end has been reached. max_lines accepts 1–1000 lines. Imported helper files are not included, so explanations should identify those limits rather than assume their behavior.

Both tools forward the caller's credentials and respect the backend's detail and source visibility rules. If PHENOWORKS_AGENT_MCP_ALLOWED_TOOLS is configured, include both new names in that allowlist. Restart the MCP server and start a new agent conversation to refresh cached tool discovery.

Shared SDK transport

MCP uses phenoworks_sdk.AsyncPhenoWorksClient for API requests, credentials, errors, and streamed downloads. The SDK is a package dependency; there is no separate MCP HTTP client. Local development resolves the sibling ../phenoworks-sdk package, and the MCP Docker image includes it.

MCP retains tool definitions, pipeline confirmation/version resolution, request-header extraction, workspace confinement, and progress reporting. Forwarded credentials are passed per request, never stored on the shared HTTP transport. API-key and bearer-token modes remain available.

The filter_datasets_by_modality tool accepts modality, optional project_id, and optional study_id. It calls the SDK's datasets.filter_by_modality helper, which filters the visible datasets' declared supported_modalities. It does not claim that a dataset already contains files of that modality.

Discover and install modules through the agent

The agent searches search_analysis_blocks(scope="installed") first and uses the account's preferred versions when preparing pipeline steps. If no suitable module is installed, it can search scope="all", including modality and data_product filters, and inspect candidates with describe_analysis_block(name, version, scope="all").

After showing the matches and the user choosing a module, install_analysis_block(name, version) displays a confirmation for that exact version. Accepting adds it to the caller's library; declining or dismissing leaves the library unchanged. A client without elicitation support must install through the Modules UI. Installation does not upload or replace a shared package.

Once installed, the agent can validate a pipeline using that version. Running the pipeline has its own separate confirmation. Start a new agent chat after updating the MCP server if an existing chat still has the previous tool definitions.

Dataset files

list_dataset_files returns a bounded page with modality, data-product, path, and exact metadata filters. get_dataset_file reads one record. Plot and survey identifiers are optional labels in metadata_json; filenames and folders do not determine those labels. get_dataset_summary reads every file page and reports file counts and metadata-based survey/plot coverage. list_data_types includes each product's administrator-controlled indexable flag. get_data_import_guide explains the three upload options and the metadata ZIP layout (one JSON sidecar per plot listing its files), with a worked example and the modalities and data products the server accepts, so agents can tell users how to organize their data before importing it.

Environmental data

get_dataset_ancillary_data(dataset_id, collection_date=None) reads persisted ancillary records through the caller-authenticated dataset API. It reports dated rainfall in millimeters and inches, temperature, humidity, wind, UTC coverage, and provider provenance. Missing values remain null; zero rainfall is an actual zero. For absent records, including an unmatched date, the tool returns found: false with No ancillary data found for this dataset.

Dataset creation automatically queues environmental data retrieval when both coordinates or a location name are provided. The UI supplies the selected collection date (default today, UTC). API callers may provide ancillary_date; without it the job explicitly records creation_date as its date basis. fetch_ancillary_data: false opts out. Name-only locations must resolve unambiguously. Recent model estimates and partial-day totals must not be described as complete measured rainfall. The tool preserves old snow-inclusive precipitation separately from rainfall.

Metadata

Release files for phenoworks-mcp 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phenoworks-mcp 0.5.0
File Size Uploaded Provenance Actions
phenoworks_mcp-0.5.0.tar.gz 55.3 kB With provenance Details for phenoworks_mcp-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phenoworks-mcp 0.5.0
File Interpreter ABI Platform Actions
phenoworks_mcp-0.5.0-py3-none-any.whl Python 3 none any Details for phenoworks_mcp-0.5.0-py3-none-any.whl

Total release size: 105.9 kB

Release files / phenoworks_mcp-0.5.0.tar.gz

Download URL phenoworks_mcp-0.5.0.tar.gz
Size 55.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d2cf2904b2a980cbb9b0484113cbf74db2d5b200c7d7ba962f4feef08e5a0c79
BLAKE2b-256 checksum
How to use checksums
929a22d55d223837087217ba342a3b3143ae6d8398305bb1cbbf0f4076b903d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Release files / phenoworks_mcp-0.5.0-py3-none-any.whl

Download URL phenoworks_mcp-0.5.0-py3-none-any.whl
Size 50.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8200e2be2a4298cbc0d09c9ba8d0944e64d1e188d40108e43e4c96c4e765cf1b
BLAKE2b-256 checksum
How to use checksums
93166f30e9b559c1725bc4a0bcb1062ecb7a4371dafe4aae7faea97034fd1d0d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

Security for phenoworks-mcp 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for phenoworks_mcp-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page