MCP · API integration guides

Search and build integration

Search public reactions by structure and conditions, then build and download datasets with their source references.

Create API key

Searches require reactions:read. Also enable construction:write when planning or building datasets.

MCP connection setup

Connect your AI client

Streamable HTTP · Bearer

Add the service URL and Authorization header in a client that supports remote MCP. Configuration formats vary; a common mcpServers example is shown below.

https://your-isynth-host/api/mcp
{
  "mcpServers": {
    "isynth": {
      "url": "https://your-isynth-host/api/mcp",
      "headers": {
        "Authorization": "Bearer <ISYNTH_AUTOMATION_TOKEN>"
      }
    }
  }
}

Replace the placeholder with an iSynth MCP credential, not a model API key. Existing credentials cannot be retrieved; revoke and replace a lost one.

Search examples

Run on the website

Use this as params for tools/call. Your MCP client handles initialization and message framing.

{
  "name": "search_reactions",
  "arguments": {
    "query": {
      "component_constraints": [
        {
          "role": "reactant",
          "mode": "substructure",
          "structure": "c1ccccc1Br"
        },
        {
          "role": "product",
          "mode": "substructure",
          "structure": "c1ccccc1N"
        }
      ],
      "bond_changes": [
        {
          "change": "broken",
          "elements": [
            "C",
            "Br"
          ],
          "role": "reactant",
          "component_slot": 1,
          "component_bond": [
            5,
            6
          ],
          "fragment_scope": "bond",
          "fragment": "[#6]:[#6](:[#6])-[#35]",
          "fragment_bond": [
            1,
            3
          ]
        },
        {
          "change": "formed",
          "elements": [
            "C",
            "N"
          ],
          "role": "product",
          "component_slot": 2,
          "component_bond": [
            5,
            6
          ],
          "fragment_scope": "bond",
          "fragment": "[#6]:[#6](:[#6])-[#7]",
          "fragment_bond": [
            1,
            3
          ]
        }
      ],
      "expand_aliases": true,
      "page_size": 5
    }
  }
}

From search to a dataset build

The current public MCP tools support reaction search, source inspection and file contribution. Use the website or switch to API for planning, building and downloading bundles; building requires explicit acceptance of the data-use agreement.

search_reactions → get_reaction
Only when needed: get_search_schema(topic=bonds|conditions|parameters)
Unfamiliar fields: get_search_fields; custom parameters: get_search_parameters
get_public_index_status (index coverage, when needed)
Search and build on the website →Data-use agreement →

How criteria match

Structures and bond changes

The drawing defines the matching environment; bond marks locate changes. Mark cleavage on reactants and formation on products. Functional groups can match anywhere in the same molecule.

Temperature, time and yield

Reported values or intervals match when they overlap the query range. Temperature and time must match the same operational stage; include room-temperature records using the page option.

Custom fields

New columns and JSON parameters are discovered in public data and filtered as numbers, text or booleans. Known units are normalized; mixed types remain text. Fields retain their source identity; combining fields across files requires verified semantic equivalence.

Use get_search_parameters to discover current fields, types, units and operators, then supply parameter_filters.

Result scope

Search covers indexed records in the latest public published versions. Results retain provenance and identify the basis for computed bond changes.