> For the complete documentation index, see [llms.txt](https://docs.pending.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pending.ai/integrations/agentic-ai/mcp-server.md).

# MCP Server

Connect directly to the Pending AI platform from any AI Agent

## Model Context Protocol

Pending AI offers a Model Context Protocol (MCP) server for accessing the different [tool options](#pending-ai-mcp-tools). An MCP server gives existing LLM chats a way to call services enabled for a user and streamline different workflows. There are many possible workflow integrations, for example:

<details>

<summary><i class="fa-messages-question">:messages-question:</i> <a data-footnote-ref href="#user-content-fn-1"><mark style="color:$primary;">Generate</mark></a> a batch of molecules and find any with an amine functional group.</summary>

{% code title="Prompt" %}

```
Generate some random molecules and find any with an amine functional group.
```

{% endcode %}

{% code title="Response (GPT-4.1)" overflow="wrap" %}

```
Here are the generated SMILES that contain an amine functional group (looked for "N", "NH", "NH2" patterns):

1. CCN(CCNCc1cnn(C)c1)C(=O)c1ccccc1N+[O-]
    - Contains secondary and primary amines.
2. C=CCNC(=O)c1cc(-c2ccc(OC)cc2)nc2c(N)c(C(N)=O)oc12
    - Contains primary amine (N), and possibly amidine/amide.
3. NC(c1cc(Br)cs1)c1ccc(Br)cc1OC(F)F
    - Contains primary amine (NC).
4. NS(=O)(=O)c1ccc2c(ccn2C2CCCN(Cc3ccc(Cl)cc3Cl)C2=O)c1
    - Contains sulfonamide (NS(=O)(=O)) and tertiary amine in the ring.
5. Cn1cnc2sc(C(=O)Nc3ccc(N)cc3)cc2c1=N
    - Contains amide (Nc3ccc(N)cc3), and aromatic amine.

These 5 SMILES from the generated set contain at least one amine functional group. Let me know if you want to analyze further or need chemical names.
```

{% endcode %}

</details>

<details>

<summary><i class="fa-messages-question">:messages-question:</i> Perform <a data-footnote-ref href="#user-content-fn-2"><mark style="color:$primary;">retrosynthesis</mark></a> on the previously generated molecules.</summary>

{% code title="Prompt" %}

```
Perform retrosynthesis on the previously generated molecules.
```

{% endcode %}

{% code title="Response (GPT-4.1)" overflow="wrap" %}

```
Retrosynthesis jobs have been submitted for the 3 generated molecules:

CC(O)C(C)Nc1nc2ncnc(SCc3ccccc3F)c2s1 — Job ID: 691e6e6f53b31257cbcbd91c
CCOC(=O)CN1C(=O)C(=Cc2ccc(N(CC)CC)cc2)C=C(CC)C1=O — Job ID: 691e6e7044369a3ca4510ae4
CC1CCCC(Nc2cc(C(F)(F)F)nc(CC3CC3)n2)CC1 — Job ID: 691e6e70f7acb63a247fa8f8
Each job is currently in "submitted" status. Let me know if you want to poll for results or retrieve the completed routes when ready.
```

{% endcode %}

</details>

<details>

<summary><i class="fa-messages-question">:messages-question:</i> Poll the retrosynthesis jobs and find the one with the longest route.</summary>

{% code title="Prompt" overflow="wrap" %}

```
Poll the retrosynthesis jobs and find the one with the longest route. 
```

{% endcode %}

{% code title="Response (Sonnet 4.5)" overflow="wrap" %}

```
Summary
After polling all 27 retrosynthesis jobs, I found the longest synthetic route:

🏆 Winner: 6-Step Synthesis
Target Molecule: CSCCCCCSc1nc2c(c(=O)[nH]1)C(N)CC2
Job ID: 691fed6eaaa8ae1c9767f0dd
Amine Type: Primary amine

The 6-Step Route:
1. Core oxidation - Oxidize tetrahydropyrimidine scaffold
2. Chlorination - Install leaving group at reactive position
3. Reductive amination - Introduce primary amine
4. Bromination - Prepare alkyl bromide linker
5. Thiol formation - Convert bromide to thiol
6. Thioether coupling - Final SNAr to connect linker to core

Key Statistics:
- Total molecules analyzed: 27
- Completed routes: 23
- Route lengths found:
  - 6 steps: 1 molecule (longest)
  - 5 steps: 1 molecule
  - 4 steps: 1 molecule
  - 3 steps: 2 molecules
  - 2 steps: 5 molecules
  - 1 step: 3 molecules

Files Created:
- View longest route analysis
- View detailed 6-step synthesis

This complex heterocyclic molecule with a bis-thiol linker represents the upper end of synthetic accessibility among the randomly generated structures, requiring sophisticated multi-step synthesis with careful functional group manipulation.
```

{% endcode %}

</details>

As Pending AI continues to deliver new possibilities, when in doubt you can always ask "What am I able to do using Pending AI?" for more information.

### Supported Tools

The Pending AI MCP server currently supports the following 22 tools in Early Access. Descriptions are the ones the server gives to your agent.

#### PAI Retro

| Tool                                     | Description                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`list_retrosynthesis_engines`**        | List retrosynthesis engines. Use this tool to show available machine learning architectures and search strategies that can be used when submitting retrosynthesis jobs. Engine choice can impact the quality and diversity of retrosynthetic routes found.                                                                |
| **`list_retrosynthesis_libraries`**      | List retrosynthesis libraries. Use this tool to show available building block libraries that can be used when submitting retrosynthesis jobs. Libraries specify collections of molecules that are available starting materials for a retrosynthetic search.                                                               |
| **`list_retrosynthesis_jobs`**           | List retrosynthesis jobs. Use this tool to get short summaries of existing jobs, or to find a job ID based on SMILES and creation timestamps. Pagination is supported via offset-based `page` and `limit` parameters.                                                                                                     |
| **`create_retrosynthesis_job`**          | Create a retrosynthesis job. Use this tool to submit a molecule for retrosynthesis screening and provide optional parameters to customise the search behavior. The molecule should be provided in SMILES format. A job ID is returned that can be used to poll the job status and retrieve results once it has completed. |
| **`retrieve_retrosynthesis_job`**        | Retrieve a retrosynthesis job. Use this tool to fetch the details of a previously created retrosynthesis job by its ID. Each job contains the molecule SMILES, status, and added timestamps for simple summary information.                                                                                               |
| **`retrieve_retrosynthesis_job_status`** | Retrieve the status of a retrosynthesis job. Expect a value that changes over time from `submitted` (waiting to be processed) to `processing` (actively being processed) to `completed` or `failed` (finished processing). Use this tool for polling the status of a job before results become available.                 |
| **`retrieve_retrosynthesis_job_result`** | Retrieve the results of a previously submitted retrosynthesis job by its ID. The list of retrosynthetic routes that were computed contain the synthetic steps to make the molecule with relevant building blocks.                                                                                                         |
| **`delete_retrosynthesis_job`**          | Delete a retrosynthesis job and generated results. The job will no longer be accessible. The operation is irreversible and should be used with caution. You cannot delete a job that is still processing.                                                                                                                 |

#### PAI Generator

| Tool                                   | Description                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`list_molecule_generator_models`**   | List generative models for sampling molecules. Use this tool to retrieve models and their metadata that can be used to see if a model is online and ready for sampling. The slower status check can be skipped when only the model metadata is needed.                                                                      |
| **`create_molecule_generator_sample`** | Sample molecules from a generative model. Molecules are represented in SMILES format and contain drug-like properties unique to the model used. Use this tool to generate novel structures that can be further filtered and evaluated. Conditional filtering should be applied after sampling to select relevant molecules. |

#### PAI Synth

| Tool                        | Description                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`create_synth_job`**      | Search for synthetic routes to a target molecule, given in SMILES format, with PAI Synth. Creates a synth job and waits up to `wait` seconds for it to finish: a completed job comes back with its routes, each listing its building blocks (with vendor pricing) and reaction steps. If the job is still `submitted` or `processing`, retrieve it with `retrieve_synth_job`. |
| **`retrieve_synth_job`**    | Retrieve a synth job by its ID, waiting up to `wait` seconds for it to finish. Its routes are filled once its status is `completed`. Works for jobs created alone or in a batch.                                                                                                                                                                                              |
| **`list_synth_jobs`**       | List synth jobs, newest first. Pagination is cursor-based: when `has_next` is true, pass `next_cursor` as `after` to get the next page.                                                                                                                                                                                                                                       |
| **`delete_synth_job`**      | Delete a synth job. The operation is irreversible and should be used with caution.                                                                                                                                                                                                                                                                                            |
| **`create_synth_batch`**    | Create a batch of synth jobs, one for each target molecule, all with the same search options. Returns at once; the jobs run in the background. Check progress with `retrieve_synth_batch` and read results with `list_synth_batch_jobs`.                                                                                                                                      |
| **`list_synth_batches`**    | List synth batches, newest first, with how many of each batch's jobs have completed. Pagination is cursor-based.                                                                                                                                                                                                                                                              |
| **`retrieve_synth_batch`**  | Retrieve a synth batch by its ID, including its status and how many of its jobs have completed.                                                                                                                                                                                                                                                                               |
| **`list_synth_batch_jobs`** | List the jobs in a synth batch, with each completed job's routes. A batch can have many jobs, so this is paginated (cursor-based).                                                                                                                                                                                                                                            |
| **`delete_synth_batch`**    | Delete a synth batch and its jobs. The operation is irreversible and should be used with caution.                                                                                                                                                                                                                                                                             |
| **`list_synth_engines`**    | List the synth engines that jobs and batches can run on, with each engine's current queue length.                                                                                                                                                                                                                                                                             |

#### Structures

| Tool                        | Description                                                                                                                                                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`depict_molecule`**       | Render a 2D structure image of a molecule or reaction from its SMILES string, returning a public image URL and a ready-made markdown image tag. A reaction SMILES (containing `>`) is drawn as a reaction.                                                    |
| **`get_molecular_formula`** | Get the molecular formula of a molecule from its SMILES string, in Hill order (e.g. `C9H8O4` for aspirin) with implicit hydrogens counted. A charged species includes its net charge, and a multi-component SMILES such as a salt gives one combined formula. |

{% hint style="info" %}
`depict_molecule` and `get_molecular_formula` call Pending AI's public structure depiction service. Your Pending AI access token isn't sent to it.
{% endhint %}

### Authentication

The MCP server is an OAuth 2.0 authorization server for MCP clients, and supports Dynamic Client Registration (DCR). When you connect from an MCP client, such as the [connectors](https://docs.pending.ai/integrations/agentic-ai/mcp-server/connectors.md) below, the client registers itself with the server and you're redirected to sign in with your Pending AI account. No client ID or callback URL needs to be set up with us first.

* The server advertises **itself** as the authorization server and proxies the sign-in to Pending AI's login page, so clients complete the flow against `https://mcp.pending.ai`, not against the login provider directly.
* A client can use any redirect URI it registers through DCR. Loopback redirect URIs (`http://localhost:<port>/...`) can use any port.
* Tool calls run as the user who signed in, and count against their team's plan, as API requests do. See [Accounts, teams and billing](https://docs.pending.ai/getting-started/accounts-and-billing.md).

[^1]: Leverage our Generative AI capabilities

[^2]: Leverage our [Retrosynthesis](https://docs.pending.ai/capabilities/retrosynthesis.md) capabilities
