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

Distinguish MCP tools from DevSpeak connectors

Create a Context Project and add assets

Enable the context7, github, and web_search connectors

Pass contextProjectId from MCP tools

Reason about fail-open grounding

Prerequisites

A working MCP connection

VIBECODER tier or higher — Context Projects start at VIBECODER, and the MCP server authenticates with an API key. VIBECODER includes one key and 50 API requests a month on the default model; DEVELOPER and above have no monthly request limit

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


This is a TypeScript monorepo using Express 5 and PostgreSQL.
All API responses use the envelope { success, data, error }.
Prefer Zod for validation. Never suggest class-based React components.

These apply to every translation 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 |


| ------------ | ---------------------------- | --------------------------------- |
| Document | PDF, Markdown, or TXT upload | Text extracted client-side        |
| Link     | A public URL                 | Fetched and extracted server-side |
| Image    | PNG, JPEG, WebP upload       | Stored and referenced             |
Link assets move through a state machine you can watch in the UI, where the states are labelled Queued, Processing, Ready, and Failed:

`text


pending → processing → ready
                    ↘ failed

The code block shows the API state names; the UI label for pending is Queued.

Only public URLs can be fetched. A link to a private or otherwise unsafe address is refused, and the asset ends in Failed.

Assets are quota-limited: 25 per project on VIBECODER, 100 on DEVELOPER, unlimited on ENTERPRISE.

`Checkpoint`

At this point you should have:

[ ] A Context Project with instructions saved


[ ] At least one asset showing Ready
[ ] The project ID from the URL or project header
Step 3 — Enable Connectors
Open the connector panel and enable what the project needs. Each connector also needs setup before it can retrieve anything:

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. Needs your own Context7 API key and at least one Context7 library ID.

github — supplies repository context so generated code matches existing structure and naming. Needs your own GitHub personal access token (fine-grained, read-only Contents and Metadata) and a repository as owner/repo.

web_search — retrieves real-time technical documentation for anything outside the other two. Needs your own Tavily API key.

Connect each credential from the connector panel. Credentials belong to you, are stored encrypted, and are used only for your requests — DevSpeak does not substitute a shared token. A connector without its credential, repository, or library ID contributes nothing, and because grounding fails open, the translation still succeeds without it.

Enable only what you need. Each connector adds a retrieval step before generation starts, so an unnecessary one slows every request in that project and makes a timeout more likely.

`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

{


  "input": "Add rate limiting to the notes endpoints.",
  "audience": "Senior Dev",
  "context": "Backend",
  "format": "Technical Spec",
  "tone": 70,
  "contextProjectId": "proj_a1b2c3"
}

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


{
  "input": "Migrate our rate limiter to the new middleware API.",
  "audience": "Senior Dev",
  "context": "Backend",
  "format": "Technical Spec",
  "tone": 70,
  "contextProjectId": "proj_a1b2c3",
  "webSearch": true
}

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, and that each enabled connector has its credential and repository or library ID.

An asset is stuck on Failed

Open the asset to see the inline reason. The usual causes are a fetch timeout, a URL refused as private or unsafe, or a file over the 10 MB limit.

Grounded requests time out

Each connector adds retrieval time, so a project with several enabled connectors is more likely to time out. Disable connectors the project does not need, starting with web_search.

HTTP 403 when creating a project

Context Projects require VIBECODER or higher. A 403 on a translate call made with an API key is a different gate: on FREE or VIBECODER the 50 monthly API requests are spent or a model was pinned, and error says which. DEVELOPER and above have no such limit.

Rapid edits return HTTP 429

Project changes are rate-limited, so a burst of edits can return 429. 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:

Separate MCP tools from DevSpeak's fixed connector registry


Create a Context Project with instructions and assets

Enable context7, github, and web_search

Ground MCP translations with contextProjectId`

Detect fail-open grounding instead of trusting it silently

Next Steps

[Handle MCP Errors, Rate Limits, and Model Selection](/tutorials/mcp/handle-errors-and-model-selection)

[Connect the DevSpeak MCP Server](/tutorials/mcp/connect-the-mcp-server)