> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withfoundry.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools reference

> Parameters and behavior of Foundry MCP server tools.

# MCP tools reference

The `@withfoundry/mcp-server` exposes these tools to Cursor (and other MCP clients). All calls use your configured `FOUNDRY_API_KEY` and the API base URL `https://api.withfoundry.ai`.

***

## Memory tools

### foundry\_memory\_write

Write one or more entries into a namespace.

| Parameter            | Type   | Required | Description                                   |
| -------------------- | ------ | -------- | --------------------------------------------- |
| `namespace`          | string | Yes      | Namespace (e.g. app or user id).              |
| `entries`            | array  | Yes      | Items with `content` and optional `metadata`. |
| `entries[].content`  | string | Yes      | Text to store.                                |
| `entries[].metadata` | object | No       | JSON for filtering/display.                   |

**Returns:** `{ ids: string[] }` — created entry ids.

**Example (as used by Cursor):**\
“Write to Foundry memory, namespace `my-app`: ‘We use API keys with prefix key\_ in the Authorization header.’”

***

### foundry\_memory\_search

Semantic search over a namespace.

| Parameter        | Type   | Required | Description                    |
| ---------------- | ------ | -------- | ------------------------------ |
| `namespace`      | string | Yes      | Namespace to search.           |
| `query`          | string | Yes      | Natural-language query.        |
| `limit`          | number | No       | Max results (e.g. 5–20).       |
| `metadataFilter` | object | No       | Key-value filters on metadata. |

**Returns:** Array of `{ id, content, metadata, score? }`.

**Example:**\
“Search Foundry memory in `my-app` for ‘how do we authenticate?’”

***

### foundry\_memory\_get\_context

Get a single context string from semantic search for use in prompts.

| Parameter   | Type   | Required | Description                        |
| ----------- | ------ | -------- | ---------------------------------- |
| `namespace` | string | Yes      | Namespace to search.               |
| `query`     | string | Yes      | Query for ranking.                 |
| `limit`     | number | No       | Max entries in the context string. |

**Returns:** `{ text: string, entryIds: string[] }`.

**Example:**\
“Get Foundry context for namespace `my-app` with query ‘user preferences and auth’, limit 3.”

***

## Security tools

### foundry\_security\_scan\_repo

Start a security scan for a repository.

| Parameter           | Type    | Required | Description                                     |
| ------------------- | ------- | -------- | ----------------------------------------------- |
| `repoUrl`           | string  | Yes      | Clone URL (e.g. `https://github.com/org/repo`). |
| `branch`            | string  | No       | Branch/ref to scan.                             |
| `waitForCompletion` | boolean | No       | If true, wait and return findings.              |

**Returns:**

* Without wait: `{ scanId, status }`.
* With wait: `{ scanId, status, findings }`.

**Example:**\
“Run a Foundry security scan on this repo” (Cursor may infer repo from workspace.)

***

### foundry\_security\_get\_scan\_result

Get status and findings for a scan.

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `scanId`  | string | Yes      | Id from `foundry_security_scan_repo`. |

**Returns:** `{ scanId, status, findings?, error? }`.

**Example:**\
“Get Foundry scan result for scan\_abc123.”

***

## Envelope and errors

The MCP server calls the REST API. API responses use the envelope:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": { "requestId": "req_..." }
}
```

On failure, the tool returns the error from `data` (or a translated message) so Cursor can show or act on it.

## Namespace tips in Cursor

* Use a stable namespace per project or user (e.g. `my-app`, `cursor-user-123`).
* Ask the AI to “search Foundry memory in namespace X for Y” so it uses the right namespace and query.