Skip to main content

Connect an AI Agent via MCP

GeniSpace exposes a standard Model Context Protocol (MCP) server. Any MCP‑compatible AI client or agent — Claude (Desktop / Code), ChatGPT connectors, Cursor, VS Code, and others — can connect to it and use your space's capabilities (agents, datasets, datasources, workflows, knowledge bases, dashboards, and more) as tools. This lets an external agent understand a requirement and build & run a complete solution on GeniSpace on your behalf.

What is MCP?

The Model Context Protocol is an open standard for connecting AI agents to external tools and data. GeniSpace's MCP server is the bridge: the agent calls GeniSpace tools, and every call runs inside the space that your API key belongs to.

Endpoint​

The server uses the standard Streamable HTTP transport. Connect to the /mcp endpoint for your region:

https://api.genispace.ai/mcp      # International
https://api.genispace.cn/mcp      # China

An unauthenticated GET https://api.genispace.ai/mcp/info returns basic connection metadata.

Self‑hosted / private deployment

On a private deployment, use your own API host (the platform operator routes the /mcp path on the API domain to the MCP service — e.g. https://api.your-domain/mcp). Ask your administrator for the exact URL.

Authentication​

Every request must carry a GeniSpace API key as a Bearer token:

Authorization: Bearer <your GeniSpace API key>
  • One key = one space. An API key is permanently bound to a single space, so everything the agent does is automatically scoped to that space. You never pass a space id — and a key cannot reach another space.
  • Create a key in the Console under Settings → Integrations, in the API key area. Store it securely (it is shown only once). See the API Authentication guide for key formats and details.
  • Least privilege. Give the key only the space.* permissions the agent needs (for example space.dataset.*, space.task.*). Treat it like a password; rotate or revoke it if exposed.
warning

Anyone holding the key can act in that space. Issue a dedicated key per integration, scope it tightly, and revoke it when no longer needed.

Connect a client​

The connection details are always the same: the URL above and an Authorization: Bearer header. Most clients accept a remote/HTTP MCP server in a config block like this:

{
  "mcpServers": {
    "genispace": {
      "type": "http",
      "url": "https://api.genispace.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_GENISPACE_API_KEY" }
    }
  }
}
tip

The exact field names differ between clients (some call it a "remote MCP server", "HTTP server", or "connector"). Whatever the format, provide the same two things: the /mcp URL and the Authorization: Bearer <key> header. Consult your client's MCP documentation for where to put them.

After connecting, the agent automatically receives the server's usage instructions and can list the available tools.

What you can do​

The server exposes a focused, navigable set of tools, plus reference documents and ready‑made templates.

Discovery tools (start here)​

ToolPurpose
genispace_list_capabilitiesList the resource groups (agents, datasets, datasources, workflows, tasks, operators, knowledge base, workbenches, config, …) you can work with.
genispace_search_capabilitiesSearch the live API for an operation that matches what you want to do.
genispace_api_requestA guard‑railed generic executor for any supported endpoint not covered by a curated tool (administrative/internal endpoints are blocked).

Curated tool groups​

GroupExamples
Agents & operatorsgenispace_agent_create (incl. strict‑schema TASK agents for structured extraction), genispace_agent_execute, genispace_operator_run, genispace_email_send
SQL datagenispace_database_create, genispace_table_create, genispace_datasource_create / _execute (a datasource is a saved, parameterized SQL statement)
Vector datasetsgenispace_dataset_create, genispace_dataset_insert, genispace_dataset_search, genispace_dataset_fulltext_search
Workflows & tasksgenispace_workflow_create, genispace_task_create (manual or scheduled with a cron), genispace_task_execute, genispace_task_status
Knowledge & configgenispace_kb_create / _search, genispace_configmap_create, genispace_configvar_set (with isSecret)
Workbenchgenispace_workbench_create (creates a WORKBENCH application and its workbench, returning a workbenchId — workbenches cannot be created directly), genispace_workbench_page_upsert (low‑code dashboards)
Space & storagegenispace_whoami, genispace_space_overview, genispace_search, genispace_apikey_create, genispace_storage_list

Reference & recipe resources​

Two areas of the platform — the workflow node/edge graph and the workbench page/component layout — are powerful but detailed. The server publishes verified, copy‑paste templates for them as MCP resources, which the agent reads on demand:

  • genispace://reference/workflow-nodes, genispace://reference/workbench-components
  • genispace://reference/sql-data, genispace://reference/vector-datasets, genispace://reference/agents-and-operators, genispace://reference/knowledge-and-config
  • genispace://docs/recipes/job-intelligence-pipeline — a complete, end‑to‑end build recipe
  • genispace://catalog/operators, genispace://catalog/api — live inventories of your space

Build prompts​

User‑invoked templates that scaffold a whole build: build_monitoring_pipeline, build_extraction_agent, build_dashboard, summarize_space.

How to work​

A reliable agent follows this loop:

  1. Discover — call genispace_list_capabilities, then genispace_search_capabilities to find the exact operation; prefer the curated genispace_* tools.
  2. Read the reference for anything involving a workflow graph or a dashboard — read genispace://reference/workflow-nodes before creating a workflow.
  3. Build in order — provision data (database → tables, and/or a dataset) → create datasources (the SQL to run) → create agents/operators → assemble a workflow → wrap it in a task (and a schedule) → optionally a workbench dashboard → store secrets in a ConfigMap.
  4. Verify — use genispace_whoami to confirm the space and permissions, and genispace_task_status after a run to inspect results.

Example: a scheduled data pipeline​

A typical end‑to‑end build (the full template is in genispace://docs/recipes/job-intelligence-pipeline):

  1. genispace_database_create → genispace_table_create for your tables.
  2. genispace_datasource_create for the SQL the workflow will run (a read for de‑duplication, an insert, an update).
  3. genispace_agent_create with agentType: "TASK" and a strict outputSchema — your structured extractor.
  4. genispace_dataset_create for semantic search/de‑duplication.
  5. Read genispace://reference/workflow-nodes, then genispace_workflow_create with the node/edge graph.
  6. genispace_task_create (type: "SCHEDULED", a cron like 0 0 6 * * *) to run it daily.
  7. Optionally genispace_workbench_create for a dashboard (it provisions a WORKBENCH application and returns a workbenchId), and genispace_configmap_create for secrets.

Limitations & notes​

  • File upload is not available over MCP (it requires multipart upload). Knowledge‑base and storage reads and search are available; ingest files through the Console first, then reference them.
  • Vector search needs embeddings. Use genispace_dataset_search with text (auto‑embedded) or the full‑text search; or compute embeddings with the multimodal-embedding operator first.
  • The workflow graph is validated when the task runs, not when it is created — follow genispace://reference/workflow-nodes exactly so the run doesn't fail.
  • Operators must be enabled for the space before they can be run.