# RevCent MCP Guide: `ProjectAssociateEntity`

AI/MCP-focused guide for associating an existing RevCent entity with a Project.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Project Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProject.md` | Explains how Projects and Project Notes should be used as the durable context trail for RevCent setup and account changes. |
| GetProject | `https://revcent.com/documentation/markdown/mcp/operation/GetProject.md` | Retrieve Project details and associated entities. |
| GetProjectNotes | `https://revcent.com/documentation/markdown/mcp/operation/GetProjectNotes.md` | Retrieve Project Notes, preferably filtered by Project. |
| CreateProjectNote | `https://revcent.com/documentation/markdown/mcp/operation/CreateProjectNote.md` | Record the reason, result, entity IDs, and follow-up after Project work. |


---

## Operation Summary

Operation:

```text
ProjectAssociateEntity
```

Purpose:

```text
Associate an existing entity with a Project.
```

Use this operation whenever an existing RevCent entity belongs to a Project, especially after creating or identifying entities during account setup, business implementation, or account changes.

---

## When to Use

Use `ProjectAssociateEntity` when:

- AI/MCP creates an entity as part of a Project,
- an existing entity should be tracked under a Project,
- the entity belongs to a WooCommerce/shop setup,
- the entity belongs to subscription, payment, shipping, tax, fulfillment, email, AI, voice, tracking, or customer portal setup,
- future AI should see the entity when calling `GetProject`.

---

## Input Schema

The live schema requires `project_id`. AI/MCP should provide all three fields for a meaningful association.

| Field | Type | Required | Description |
|---|---:|---:|---|
| `project_id` | string | Yes | 20-character Project ID. |
| `entity_type` | string | Strongly required for practical use | Entity type enum. |
| `entity_id` | string | Strongly required for practical use | 20-character entity ID. If associating `key_value`, use the key instead of an ID. |

Example:

```json
{
  "project_id": "XXXXXXXXXXXXXXXXXXXX",
  "entity_type": "subscription_profile",
  "entity_id": "YYYYYYYYYYYYYYYYYYYY"
}
```

---

## Supported `entity_type` Values

| `entity_type` | Entity |
|---|---|
| `campaign` | Campaign |
| `ai_assistant` | AI Assistant |
| `ai_voice_agent` | AI Voice Agent |
| `ai_voice_snippet` | AI Voice Snippet |
| `ai_prompt` | AI Prompt |
| `key_value` | Key Value. Use the key as `entity_id`. |
| `bin_profile` | BIN Profile |
| `customer_group` | Customer Group |
| `customer_portal` | Customer Portal |
| `email_template` | Email Template |
| `fulfillment_account` | Fulfillment Account |
| `product` | Product |
| `product_group` | Product Group |
| `custom_function` | Function / Custom Function |
| `gateway` | Gateway |
| `gateway_group` | Gateway Group |
| `smtp_profile` | SMTP Profile |
| `paypal_account` | PayPal Account |
| `payment_profile` | Payment Profile |
| `shipping_profile` | Shipping Profile |
| `subscription_profile` | Subscription Profile |
| `url_parameter_set` | URL Parameter Set |
| `third_party_shop` | Third-Party Shop / Shop |
| `third_party_integration` | Third-Party Integration |
| `tracking_domain` | Tracking Domain |

Important:

```text
For Functions, use `custom_function` as the entity_type.
```

---

## Output Schema

Successful output can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `project_id` | 20-character Project ID. |
| `entity_type` | Entity type associated with the Project. |
| `entity_id` | Entity ID associated with the Project. |
| `result` | Result message. |

---

## Recommended Workflow

```text
1. Identify the relevant Project.
2. Create or identify the entity.
3. Run ProjectAssociateEntity.
4. CreateProjectNote explaining why the entity was associated.
5. Run GetProject to verify the entity appears under the Project.
```

---

## Project Note Example

```text
[2026-06-04] Associated Shipping Profile "US Subscription Shipping" with the Acme WooCommerce Implementation Project.

Reason:
- Profile is required for subscription renewals and trial expirations involving shippable products.
- Future AI should treat this Shipping Profile as part of the Acme shop setup.

Related entities:
- Project ID: XXXXXXXXXXXXXXXXXXXX
- Shipping Profile ID: YYYYYYYYYYYYYYYYYYYY
```

---

## Project Note Tracking Rule

Project-related operations should almost always be paired with Project Notes.

Use Project Notes to record:

- what changed,
- why it changed,
- who/what requested the change,
- related entity IDs,
- whether the change affects global/shared configuration,
- follow-up work,
- warnings for future AI/MCP interactions.

Recommended note format:

```text
[YYYY-MM-DD] Short action summary

Context:
- Why this was done
- User decision or constraint

Changes:
- Operation(s) performed
- Entity names and IDs

Follow-up:
- Remaining work
- Warnings or confirmation requirements
```



---

## Common Mistakes to Avoid

Do not:

- create entities without associating them with the Project,
- associate entities with the wrong Project,
- use `function` instead of `custom_function`,
- associate an entity without a Project Note explaining why,
- assume association edits the underlying entity.

---

## Final AI/MCP Instruction

Use `ProjectAssociateEntity` whenever an existing RevCent entity belongs to a Project. Always follow the association with `CreateProjectNote` so future AI knows why the entity was associated.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.