Tutorial on grounding DevSpeak MCP translations with Context Projects. Explains why MCP tools differ from DevSpeak's fixed connector registry, how to create a project and add document, link, and image assets, how the context7, github, and web_search connectors supply library docs, repository context, and web results, and how to pass contextProjectId to translate_text and refine_translation. Documents fail-open grounding, where an unknown project or failed connector degrades to an ungrounded request instead of erroring, plus the asset ingestion states pending, processing, ready, and failed.

Ground MCP Translations on a Context Project

By default every translation starts cold. It knows your parameters and nothing about your codebase, your naming conventions, or the library versions you actually run.

Context Projects fix that. A project holds instructions, ingested assets, and a set of connectors — and it carries across every translation you run against it.

What You'll Learn

Prerequisites

Time Estimate

~11 minutes

First, a Distinction That Trips People Up

These are two different layers, and conflating them causes real confusion:

| Layer | Examples | Who calls it |

| -------------- | -------------------------------------- | ----------------------------- |

| MCP tools | translate_text, refine_translation | Your AI assistant |

| Connectors | context7, github, web_search | DevSpeak's server, internally |context7 is not something your assistant invokes. It is one of three connectors in DevSpeak's fixed registry, enabled per Context Project and consulted server-side while building the prompt. You never call it directly — you enable it, then reference the project.

The registry is frozen. There is no runtime registration path, and the three connectors below are the complete set.

Step 1 — Create a Context Project

In the DevSpeak dashboard, open PROJECTS in the sidebar and create one.

Give it instructions that apply to every translation in the project:

``text

`

These are prepended to every prompt grounded on this project. Constraints you would otherwise retype into customInstructions on each call belong here.

Step 2 — Add Assets

Three asset kinds are supported:

| Kind | Source | Ingestion |

`text

`

Fetching is SSRF-guarded. Every redirect hop — up to three — is re-validated against the public-URL guard, so a link that redirects to a private address fails rather than reaching an internal service.

Assets are quota-limited: 25 per project on Vibecoder, 100 on Developer, unlimited on Enterprise.

Checkpoint

At this point you should have:

context7 — pulls current library documentation. Valuable because model training data lags real releases; this is how a translation gets the API you actually run rather than the one from two majors ago.

github — supplies repository context so generated code matches existing structure and naming.

web_search — retrieves real-time technical documentation for anything outside the other two.

Enable only what you need. Each connector adds a retrieval step before generation starts, so an unnecessary one makes every request in that project slower and brings it closer to timing out.

Step 4 — Ground a Translation

Pass the project ID as contextProjectId:

> Use translate_text with contextProjectId "proj_a1b2c3", audience "Senior Dev", context "Backend", format "Technical Spec", and tone 70.

`json

{

`

The output now references your actual envelope shape, uses Zod, and targets Express 5 — because the instructions said so.

refine_translation accepts the same parameter. Pass it on both calls, or a refinement will lose the grounding the original translation had.

Grounding Fails Open — Understand This

This is the most important behavior in the feature:

> If contextProjectId is unknown, your tier lacks Context Projects, or a connector fails, the request still succeeds — ungrounded.

There is no error. You get a normal translation that simply ignored your project.

This is a deliberate availability tradeoff: a failing connector should not break translation. But it means a typo'd project ID looks like success while silently producing generic output.

How to tell grounding actually applied: check the output for something only your project knows. If your instructions specify the { success, data, error } envelope and the output invents a different shape, grounding did not apply. Verify the ID and confirm your tier includes the feature.

Combining Grounding With Web Search

contextProjectId and the webSearch flag are independent and compose:

`json

`

The project supplies your conventions; webSearch supplies current upstream documentation. Together they produce a migration plan grounded in both.

Troubleshooting

Output ignores my project instructions

Grounding failed open. Verify the project ID exactly, confirm your tier with get_account_info, and check that assets show ready rather than failed.

An asset is stuck on failed

Open the asset to see the inline reason. The usual causes are a fetch timeout, a URL that failed SSRF re-validation on redirect, or a file over the 10 MB limit.

Grounded requests time out

Each connector adds retrieval time against the fixed wall. Disable connectors the project does not need, starting with web_search.

HTTP 403 when creating a project

Context Projects require Vibecoder or higher.

Rapid edits return HTTP 429

Project mutations sit behind a strict rate limiter (25 requests per 5 minutes). The response carries Retry-After in both a header and a retryAfter field. The dashboard debounces edits into a single request; scripted callers should honor that value.

Summary

You've learned how to:

Next Steps